Pinal Developers

Guide

Sign in with Pinal

Pinal Accounts is a standards-compliant OpenID Connect provider. If you've used OAuth anywhere else, you already know how this works.

Endpoints

Issuerhttps://accounts.pinal.tech
Discoveryhttps://accounts.pinal.tech/.well-known/openid-configuration
Authorizehttps://accounts.pinal.tech/api/auth/oauth2/authorize
Tokenhttps://accounts.pinal.tech/api/auth/oauth2/token
UserInfohttps://accounts.pinal.tech/api/auth/oauth2/userinfo
Revokehttps://accounts.pinal.tech/api/auth/oauth2/revoke
End sessionhttps://accounts.pinal.tech/api/auth/oauth2/end-session
JWKShttps://accounts.pinal.tech/api/auth/jwks

With a library

Point any OIDC client at the issuer and it configures itself from the discovery document. For example, with openid-client in Node:

import * as client from 'openid-client';

const config = await client.discovery(
  new URL('https://accounts.pinal.tech'),
  'YOUR_CLIENT_ID',
  'YOUR_CLIENT_SECRET'
);

const verifier = client.randomPKCECodeVerifier();
const url = client.buildAuthorizationUrl(config, {
  redirect_uri: 'https://example.com/auth/callback',
  scope: 'openid profile email calendar.read',
  code_challenge: await client.calculatePKCECodeChallenge(verifier),
  code_challenge_method: 'S256'
});

The rules

  • Authorization code with PKCE (S256) only. No implicit flow, no password grant.
  • Redirect URIs match exactly, including the path and trailing slash. https is required except for http://localhost.
  • Scopes are per app. Ask for a scope your app isn't configured with and the request fails with invalid_scope.
  • Silent sign-in is for Pinal's own apps. Third-party apps get interaction_required for prompt=none, so no site can quietly check whether someone is signed in.

Tokens

Access tokens last one hour. ID tokens are RS256-signed JWTs. With offline_access you also get a refresh token, valid for 30 days and rotated on each use:

curl -X POST https://accounts.pinal.tech/api/auth/oauth2/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

The consent screen

People see your icon, name, description, homepage and who made the app, then the permissions you asked for grouped by service. Each group expands to show every scope. Scopes that act on someone's behalf (like mail.send) are flagged.

People can review and remove your app's access at any time from their Pinal account. Handle invalid_token by sending them through sign-in again.

Signing out

Clear your own session, then send the browser to the end-session endpoint to sign out of Pinal too:

https://accounts.pinal.tech/api/auth/oauth2/end-session
  ?client_id=YOUR_CLIENT_ID
  &id_token_hint=ID_TOKEN
  &post_logout_redirect_uri=https://example.com/