# Sign agents in

> An agent signs in to your site with no person present: it exchanges a request signed with its agent key for a ten-minute ID token for your site, then signs every request it sends you with the same key. Your site checks both, so a copied token is useless alone. The same exchange gives an MCP server’s authorization server an ID-JAG.

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

## The agent’s side

The site’s `client_id` is the `audience`. The site tells you it, or shows it on its sign-in page.

TypeScript:

```ts
import { signedFetch } from '@pidgeon-ai/sdk';
import { signInAsAgent } from '@pidgeon-ai/sdk/auth';

const directory = 'https://acme.agents.pidgeon.ai';
const { idToken } = await signInAsAgent({
  site: 'site_q8Zr2mX4k1Vb7nPw0sTe',
  key,            // { kid, privateJwk }
  directory,
});

await signedFetch('https://shop.example/api/orders', {
  method: 'POST',
  headers: { authorization: `Bearer ${idToken}` },
}, { privateJwk: key.privateJwk, directory });
```

Python:

```python
from pidgeon import signed_client
from pidgeon.auth import sign_in_as_agent

directory = "https://acme.agents.pidgeon.ai"
session = sign_in_as_agent("site_q8Zr2mX4k1Vb7nPw0sTe", key.private_jwk, directory)
shop = signed_client(key.private_jwk, directory,
                     headers={"authorization": f"Bearer {session.id_token}"})
shop.post("https://shop.example/api/orders")
```

### The exchange, without the SDK

`POST /oauth/token`, form-encoded, carrying the [signature headers](https://pidgeon.ai/docs/signing-requests.md#headers) made with the key named in `subject_token`.

Request:

```http
POST /oauth/token HTTP/1.1
Host: pidgeon.ai
Content-Type: application/x-www-form-urlencoded
Signature-Agent: "https://acme.agents.pidgeon.ai"
Signature-Input: sig1=("@authority" "signature-agent" "@method" "@path" "@query");…;tag="web-bot-auth"
Signature: sig1=:…:

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=KUqU0uc-fPnz0RGiU5gdnMXYaa6FUqqDKcy-oa90dkQ
&subject_token_type=urn:pidgeon:params:oauth:token-type:agent-key
&audience=site_q8Zr2mX4k1Vb7nPw0sTe
```

Response:

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6…",
  "issued_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_type": "N_A",
  "expires_in": 600
}
```

`access_token` is the ID token. The key, the agent and its operator must be live, and `Signature-Agent` must name the operator’s own directory, the one that publishes the key (`https://<slug>.agents.pidgeon.ai`, bare or with its `/.well-known/http-message-signatures-directory` path); the exchange counts as one agent sign-in on the site’s account ([pricing](https://pidgeon.ai/docs/pricing.md#sign-in-prices)). One signed request gets one token: the same headers sent again are refused (`invalid_grant`, `used already`), so a retry signs again, as the SDKs do on every call.

## The site’s side

Accept the agent’s request only when the ID token is Pidgeon’s and for you, the request is signed with the key the token names in `cnf.jwk` (RFC 7800), and its `Signature-Agent` names the agent’s own directory, `agent.directory` in the token. `verifyAgentSignIn` checks all three.

TypeScript:

```ts
import { verifyAgentSignIn, SignInError } from '@pidgeon-ai/sdk/auth';

try {
  const claims = await verifyAgentSignIn(request, { clientId: 'site_q8Zr2mX4k1Vb7nPw0sTe' });
  claims.sub;        // the agent's id: your account key for it
  claims.agent;      // { name, purpose, directory }
  claims.account;    // { name, slug, verification }
  claims.reputation; // 'unverified' | 'new' | 'good' | 'flagged' | 'suspended'
} catch (error) {
  if (error instanceof SignInError) return new Response(error.message, { status: 401 });
  throw error;
}
```

Python:

```python
from pidgeon.auth import verify_agent_sign_in, SignInError

try:
    claims = verify_agent_sign_in(request.method, str(request.url), request.headers,
                                  "site_q8Zr2mX4k1Vb7nPw0sTe")
except SignInError as error:
    return unauthorized(str(error))
```

Claims:

```json
{
  "iss": "https://pidgeon.ai",
  "sub": "0b6d1c5e-8f2a-4e7b-9c1d-2a3b4c5d6e7f",
  "aud": "site_q8Zr2mX4k1Vb7nPw0sTe",
  "iat": 1794683000,
  "exp": 1794683600,
  "kind": "agent",
  "account": { "name": "Acme GmbH", "slug": "acme", "verification": "kyb" },
  "agent": {
    "name": "Acme booking agent",
    "purpose": "Books train tickets for Acme's customers",
    "directory": "https://acme.agents.pidgeon.ai"
  },
  "reputation": "good",
  "pod": "7c6b5a49-3827-4161-9f0e-d1c2b3a49586",
  "email": "booking@pidgeon.email",
  "email_verified": true,
  "cnf": { "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "dMKP5VcjdGbkRnRofDfKtlHY6Dw_asIbny9W38rai9s" } }
}
```

`email` is present when an inbox is linked to the agent identity. On the site’s side, `SignInError.reason` is `invalid_token` (not a valid Pidgeon ID token for you), `not_an_agent` (a person’s token, or no `cnf`), `unsigned` (no token or no signature), `wrong_key` (signed with another key than the one in `cnf`), `wrong_request` (the signature does not cover this request: another method, path or host), `expired` (the signature is over five minutes old, past its expiry, or dated ahead), `wrong_directory` (`Signature-Agent` is not the agent’s own directory) or `mandate_ended` (with `clientSecret`, the token’s [mandate was stopped](https://pidgeon.ai/docs/mandates.md#stopping) or ran out). On the agent’s side, `signInAsAgent` and `requestIdJag` throw `refused` when Pidgeon refuses the exchange (any of the [errors below](#errors)), or when Pidgeon refuses the mandate check because the client secret is wrong; the message is Pidgeon’s `error_description`.

## For an MCP server: ID-JAG

When an MCP server’s authorization server trusts Pidgeon as an identity provider (MCP Enterprise-Managed Authorization), the agent asks for an Identity Assertion JWT Authorization Grant ([draft-ietf-oauth-identity-assertion-authz-grant](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/)) with the same signed exchange, and presents it there as a JWT bearer grant (RFC 7523).

TypeScript:

```ts
import { requestIdJag } from '@pidgeon-ai/sdk/auth';

const { idJag } = await requestIdJag({
  audience: 'https://auth.example.com',                     // the authorization server's issuer
  clientId: 'https://agent.example.com/oauth/client.json',  // your client id there
  resource: 'https://mcp.example.com/mcp',
  key,
  directory: 'https://acme.agents.pidgeon.ai',
});
// Then, at that server: grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<idJag>
```

Python:

```python
from pidgeon.auth import request_id_jag

id_jag = request_id_jag("https://auth.example.com",
                        "https://agent.example.com/oauth/client.json",
                        key.private_jwk, "https://acme.agents.pidgeon.ai",
                        resource="https://mcp.example.com/mcp")
```

Form:

```text
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&requested_token_type=urn:ietf:params:oauth:token-type:id-jag
&subject_token=<kid>
&subject_token_type=urn:pidgeon:params:oauth:token-type:agent-key
&audience=https://auth.example.com
&client_id=https://agent.example.com/oauth/client.json
&resource=https://mcp.example.com/mcp
&scope=<optional, up to 1,000 characters>
```

- The ID-JAG is a JWT of type `oauth-id-jag+jwt`, RS256 with Pidgeon’s published key, valid five minutes, never refreshed. `sub` is the agent; it carries `aud`, `client_id`, `jti` and the agent’s claims.
- `audience` is exactly one https issuer; `resource` must be https.
- Not metered: the authorization server has no Pidgeon account to charge. Not available under a mandate.

## Errors

| `error` | When |
| --- | --- |
| `invalid_request` | A wrong `subject_token_type` or `requested_token_type`, not exactly one audience, or no `client_id` for an ID-JAG. |
| `invalid_grant` | The description says which: no signature; signed with another key than `subject_token`; no published key with that id; the signature expired, is over five minutes old or dated ahead; the signature does not match the request; `Signature-Agent` is not the directory that publishes the key; the same signed request used already; or the key, agent or operator is no longer active. |
| `invalid_target` | The audience is not a site registered with Sign in with Pidgeon; for an ID-JAG, the audience is Pidgeon or a client registered with it; or the resource is not https. |
| `access_denied` | The site has used its free agent sign-ins this month and usage billing is off. |
