Sign in with Pidgeon

Sign people in

Let people sign in to your site with their Pidgeon account through standard OpenID Connect: the authorization code flow with PKCE (S256), your client secret at the token endpoint, and an RS256 ID token for your site. Any OpenID Connect library works; no Pidgeon SDK is needed.

1. Send the person to Pidgeon

URL
https://pidgeon.ai/oauth/authorize
  ?response_type=code
  &client_id=site_q8Zr2mX4k1Vb7nPw0sTe
  &redirect_uri=https%3A%2F%2Fshop.example%2Fauth%2Fcallback
  &scope=openid%20email%20profile
  &state=<random>
  &nonce=<random>
  &code_challenge=<base64url SHA-256 of the verifier>
  &code_challenge_method=S256
  • scope must include openid. email adds email and email_verified; profile adds name: the name the person gave Pidgeon (Settings, or the one their Google account brought). A person who gave none has no name claim: show their email, or ask them for a name on your site.
  • PKCE is required: code_challenge_method=S256 and a 43-character challenge.
  • nonce, up to 255 characters, comes back in the ID token.
  • prompt=none never shows a page and is never a silent yes, since Pidgeon asks the person every time: it answers login_required (not signed in to Pidgeon), interaction_required (no account yet) or consent_required. It cannot be combined with another prompt value.

The person signs in to Pidgeon if they are not yet, and the consent screen says what your site learns. Pidgeon then redirects to redirect_uri with code, state and iss=https://pidgeon.ai, or with error and error_description.

2. Exchange the code

Authenticate with your secret by HTTP Basic (client_secret_basic) or in the body (client_secret_post). redirect_uri must be the same as in step 1. A code lasts ten minutes and works once; presented a second time, it is refused and the sign-in it made ends: its access token stops reading userinfo (RFC 6749 §4.1.2).

curl https://pidgeon.ai/oauth/token \
  -u "site_q8Zr2mX4k1Vb7nPw0sTe:$PIDGEON_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=<the code> \
  -d redirect_uri=https://shop.example/auth/callback \
  -d code_verifier=<the verifier>

There is no refresh token for a sign-in. The access token reads /oauth/userinfo for an hour and nothing else.

3. Check the ID token

import { verifyIdToken } from '@pidgeon-ai/sdk/auth';

const claims = await verifyIdToken(idToken, { clientId: 'site_q8Zr2mX4k1Vb7nPw0sTe', nonce });
claims.sub;   // the person's id at Pidgeon: your key for them
claims.email; // with the email scope

verifyIdToken checks the RS256 signature against Pidgeon’s published key, the issuer, your client id as audience, the expiry (ten minutes), the nonce, and that the token is an ID token (typ JWT, never an ID-JAG). account is the Pidgeon account the person belongs to.

Userinfo

curl
curl https://pidgeon.ai/oauth/userinfo -H "Authorization: Bearer pgn_oat_…"

Answers the same claims as the ID token (without iss, aud, exp), or 401 with WWW-Authenticate: Bearer error="invalid_token".

Errors

The token endpoint answers OAuth errors (RFC 6749): {"error", "error_description"}.

errorWhen
invalid_clientThe client id or secret is wrong (401).
invalid_requestNo code, or no valid code_verifier.
invalid_grantThe code is unknown or used (already used), past its ten minutes (expired), or does not match the client, redirect or verifier; the description says which.
unsupported_grant_typeNot authorization_code, refresh_token or token exchange.
slow_downToo many requests (429).