Pinal Developers

API reference

Sign in with Pinal

OAuth 2.1 and OpenID Connect on Pinal Accounts: send people to sign in, get tokens, find out who they are.

Base URL https://accounts.pinal.tech

Discovery document

GET /.well-known/openid-configuration

OpenID Connect discovery metadata: every endpoint, supported scope, grant and signing algorithm. Point your OIDC library here and it configures itself.

No token needed

Responses

curl "https://accounts.pinal.tech/.well-known/openid-configuration"
Response · 200
{
  "issuer": "https://accounts.pinal.tech",
  "authorization_endpoint": "https://accounts.pinal.tech/api/auth/oauth2/authorize",
  "token_endpoint": "https://accounts.pinal.tech/api/auth/oauth2/token",
  "userinfo_endpoint": "https://accounts.pinal.tech/api/auth/oauth2/userinfo",
  "jwks_uri": "https://accounts.pinal.tech/api/auth/jwks",
  "code_challenge_methods_supported": [
    "S256"
  ]
}

Start sign-in

GET /api/auth/oauth2/authorize

Send the person's browser here. They sign in to Pinal Accounts (if they aren't already), see your app's consent screen, and come back to redirect_uri with a code and your state. PKCE (S256) is required for every app.

No token needed

Query parameters

  • response_type string required

    Always code.

    One of code

  • client_id string required

    Your app's client ID.

  • redirect_uri string required

    One of your app's redirect URIs, exactly as registered.

  • scope string required

    Space-separated scopes. Must be a subset of the scopes your app is allowed.

  • state string required

    An unguessable value you check when the person comes back.

  • code_challenge string required

    BASE64URL(SHA256(code_verifier)).

  • code_challenge_method string required

    Always S256.

    One of S256

  • nonce string

    Echoed in the ID token, to bind it to this sign-in.

  • prompt string

    login to force a fresh sign-in, consent to show the consent screen again.

    One of loginconsentselect_account

Responses

curl "https://accounts.pinal.tech/api/auth/oauth2/authorize?response_type=%7Bresponse_type%7D&client_id=pnl_7Hq2xV9kLmA1&redirect_uri=%7Bredirect_uri%7D&scope=openid%20profile%20email&state=%7Bstate%7D&code_challenge=%7Bcode_challenge%7D&code_challenge_method=%7Bcode_challenge_method%7D"

Get tokens

POST /api/auth/oauth2/token

Exchange an authorization code (or a refresh token) for tokens. Confidential apps authenticate with HTTP Basic (client_id:client_secret); public apps send client_id and rely on PKCE.

No token needed

Request body application/x-www-form-urlencoded

  • grant_type string required

    One of authorization_code refresh_token

  • code string

    From the redirect (authorization_code).

  • redirect_uri string

    Same value as in the authorize request.

  • code_verifier string

    The PKCE verifier.

  • refresh_token string

    For grant_type=refresh_token.

  • client_id string

    Public clients only; confidential clients use HTTP Basic.

Responses

curl -X POST "https://accounts.pinal.tech/api/auth/oauth2/token" \
  -d grant_type=authorization_code \
  -d code=Sx8Qm… \
  -d redirect_uri=https://example.com/auth/callback \
  -d code_verifier=dBjftJeZ4CVP…
Response · 200
{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_9c1…",
  "id_token": "eyJhbGciOi…",
  "scope": "openid profile email"
}

Who's signed in

GET /api/auth/oauth2/userinfo

Claims about the person, limited to the scopes they granted: sub always; name and picture with profile; email and email_verified with email.

Responses

curl "https://accounts.pinal.tech/api/auth/oauth2/userinfo" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "sub": "usr_2k9d",
  "name": "Alex Rivera",
  "email": "alex@pinal.email",
  "email_verified": true,
  "picture": "https://accounts.pinal.tech/avatars/usr_2k9d.png"
}

Revoke a token

POST /api/auth/oauth2/revoke

Revoke an access or refresh token, e.g. when someone disconnects inside your app. Revoking a refresh token also ends the access tokens issued from it.

No token needed

Request body application/x-www-form-urlencoded

  • token string required
  • token_type_hint string

    One of access_token refresh_token

Responses

curl -X POST "https://accounts.pinal.tech/api/auth/oauth2/revoke" \
  -d token=string \
  -d token_type_hint=access_token

Sign out

GET /api/auth/oauth2/end-session

RP-initiated logout. Ends the person's Pinal session and returns them to one of your sign-out redirect URIs.

No token needed

Query parameters

  • id_token_hint string

    The ID token you received at sign-in.

  • client_id string

    Your client ID.

  • post_logout_redirect_uri string

    One of your registered sign-out redirect URIs.

  • state string

    Echoed back.

Responses

curl "https://accounts.pinal.tech/api/auth/oauth2/end-session"

Signing keys

GET /api/auth/jwks

Public keys (JWKS) for verifying ID tokens and JWT access tokens.

No token needed

Responses

curl "https://accounts.pinal.tech/api/auth/jwks"
Response · 200
{}