# 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.

Source: https://pidgeon.ai/docs/auth-people

## 1. Send the person to Pidgeon

URL:

```text
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:

```bash
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>
```

Response:

```json
{
  "access_token": "pgn_oat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6…",
  "scope": "openid email profile"
}
```

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

TypeScript:

```ts
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
```

Python:

```python
from pidgeon.auth import verify_id_token

claims = verify_id_token(id_token, "site_q8Zr2mX4k1Vb7nPw0sTe", nonce=nonce)
```

Claims:

```json
{
  "iss": "https://pidgeon.ai",
  "sub": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "aud": "site_q8Zr2mX4k1Vb7nPw0sTe",
  "iat": 1794683000,
  "exp": 1794683600,
  "nonce": "<your nonce>",
  "kind": "person",
  "account": { "name": "Ana Lima", "slug": "ana-lima", "verification": "domain" },
  "email": "ana@example.com",
  "email_verified": true,
  "name": "Ana Lima"
}
```

`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

```bash
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). |
