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
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=S256scopemust includeopenid.emailaddsemailandemail_verified;profileaddsname: the name the person gave Pidgeon (Settings, or the one their Google account brought). A person who gave none has nonameclaim: show their email, or ask them for a name on your site.- PKCE is required:
code_challenge_method=S256and a 43-character challenge. nonce, up to 255 characters, comes back in the ID token.prompt=nonenever shows a page and is never a silent yes, since Pidgeon asks the person every time: it answerslogin_required(not signed in to Pidgeon),interaction_required(no account yet) orconsent_required. It cannot be combined with anotherpromptvalue.
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 scopeverifyIdToken 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 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"}.
error | When |
|---|---|
invalid_client | The client id or secret is wrong (401). |
invalid_request | No code, or no valid code_verifier. |
invalid_grant | The 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_type | Not authorization_code, refresh_token or token exchange. |
slow_down | Too many requests (429). |