# Sign in with Pidgeon

> Let AI agents sign in to your app as themselves, and people too. Sign in with Pidgeon is one OpenID Connect provider at `https://pidgeon.ai` that signs people in with the code flow and PKCE, and signs agents in with no person present, by a request signed with their agent identity’s key ([Agent identity](https://pidgeon.ai/docs/passport.md)). Register your site (in the dashboard or by API) to get a client id and secret, then follow the page for people or for agents.

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

## Register your site

`POST /v1/auth/clients` with an API key of `admin` access. The `client_secret` is answered once; Pidgeon keeps only its hash.

curl:

```bash
curl https://pidgeon.ai/v1/auth/clients \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop Example", "redirect_uris": ["https://shop.example/auth/callback"]}'
```

Response 201:

```json
{
  "client_id": "site_q8Zr2mX4k1Vb7nPw0sTe",
  "name": "Shop Example",
  "redirect_uris": ["https://shop.example/auth/callback"],
  "pod_id": null,
  "created_at": "2026-11-14T11:20:05.441Z",
  "client_secret": "pgn_cs_…"
}
```

| Field | Value |
| --- | --- |
| `name` | Required. What the consent screen calls your site, up to 120 characters. |
| `redirect_uris` | Required. 1 to 20 https addresses, matched exactly; `http` only on `localhost`, `127.0.0.1` or `[::1]`. No fragment, no user name or password. A `400` names the address and the rule it breaks. |
| `pod_id` | The pod the site belongs to. A key of one pod registers in its own pod. |

| Call | Access | Answers |
| --- | --- | --- |
| `GET /v1/auth/clients` | `read` | `{data: [site…]}`, without secrets. |
| `DELETE /v1/auth/clients/{client_id}` | `admin` | `204`. The site stops signing anyone in, and its sign-ins end. |

Or register it in the dashboard: Auth → Sites, or `/start/auth`, which also hands your coding agent a prompt that adds the button.

## Edit a site, rotate its secret

`PATCH /v1/auth/clients/{client_id}` renames a site or replaces its return addresses, checked as registering checks them. `redirect_uris` is the whole new list, not an addition. The `client_id` and the secret stay, and sign-ins already made stay; a sign-in in flight to an address you took off fails at the token endpoint.

```bash
curl -X PATCH https://pidgeon.ai/v1/auth/clients/site_q8Zr2mX4k1Vb7nPw0sTe \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uris": ["https://shop.example/auth/callback", "https://staging.shop.example/auth/callback"]}'
```

`POST /v1/auth/clients/{client_id}/rotate-secret` answers a new `client_secret`, once. The old secret stops working at once, with no overlap, since a rotation is most often for a secret that leaked: put the new one on your server straight away, or sign-ins fail at the token endpoint until you do. Tokens already issued are not affected.

| Call | Access | Answers |
| --- | --- | --- |
| `PATCH /v1/auth/clients/{client_id}` | `admin` | The site, without its secret. |
| `POST /v1/auth/clients/{client_id}/rotate-secret` | `admin` | The site, with its new `client_secret` this once. |

A key of one pod reaches its own pod’s sites only. In the dashboard: Auth → Sites → the site → **Edit** or **Rotate secret**.

## Discovery and keys

Any OpenID Connect library configures itself from the issuer. ID tokens are RS256, signed with the key at `/.well-known/jwks.json`.

curl:

```bash
curl https://pidgeon.ai/.well-known/openid-configuration
curl https://pidgeon.ai/.well-known/jwks.json
```

openid-configuration:

```json
{
  "issuer": "https://pidgeon.ai",
  "authorization_endpoint": "https://pidgeon.ai/oauth/authorize",
  "token_endpoint": "https://pidgeon.ai/oauth/token",
  "userinfo_endpoint": "https://pidgeon.ai/oauth/userinfo",
  "jwks_uri": "https://pidgeon.ai/.well-known/jwks.json",
  "registration_endpoint": "https://pidgeon.ai/oauth/register",
  "revocation_endpoint": "https://pidgeon.ai/oauth/revoke",
  "introspection_endpoint": "https://pidgeon.ai/oauth/introspect",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email", "read", "draft", "send", "admin"],
  "claims_supported": ["iss", "sub", "aud", "exp", "iat", "nonce", "kind", "name", "email",
                       "email_verified", "account", "agent", "reputation", "pod", "cnf",
                       "act", "mandate", "scope"],
  "grant_types_supported": ["authorization_code", "refresh_token",
                            "urn:ietf:params:oauth:grant-type:token-exchange"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "client_id_metadata_document_supported": true,
  "authorization_response_iss_parameter_supported": true,
  "identity_chaining_requested_token_types_supported": ["urn:ietf:params:oauth:token-type:id-jag"],
  "id_jag_signing_alg_values_supported": ["RS256"]
}
```

`registration_endpoint` is open dynamic client registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) for apps that connect to a person’s account and cannot publish a client metadata document: MCP clients and other connected apps ([OAuth for apps](https://pidgeon.ai/docs/api-keys.md#oauth-apps)). It registers public clients only, with no secret, so it is not how a site signs people in: register your site above for a client secret. A client registered this way that nobody connects, signs in or names in a mandate within 30 days is deleted.

There is no `end_session_endpoint`: Pidgeon has no RP-initiated logout. Signing out of your site ends your own session; Pidgeon’s ID token is not a session and expires in ten minutes. To end what your site holds at Pidgeon, revoke the sign-in’s access token at `revocation_endpoint`. A person signs out of Pidgeon itself in Pidgeon.

## Who signs in

| Who | How | Page |
| --- | --- | --- |
| A person | Authorization code with PKCE, after signing in to Pidgeon. Free. | [People](https://pidgeon.ai/docs/auth-people.md) |
| An agent, as itself | Token exchange (RFC 8693), the request signed with its agent key. One agent sign-in on your meter. | [Agents](https://pidgeon.ai/docs/auth-agents.md) |
| An agent, for a person | The same exchange under a mandate the person gave it. | [Mandates](https://pidgeon.ai/docs/mandates.md) |

Every ID token says which with `kind`: `person` or `agent`. A sign-in never becomes an API key: its tokens are refused by `/v1`.

See all three live at [demo.pidgeon.ai](https://demo.pidgeon.ai), our own site that signs in with Pidgeon: sign in as yourself, watch an agent sign in, then let it sign in as you, and read the claims each time. Your own agent can sign in there too: `GET https://demo.pidgeon.ai/api/whoami` without a token answers the `client_id` and `issuer` to use, and with one answers the claims the site accepted.
