Sign in with Pidgeon
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.
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.
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 });The exchange, without the SDK
POST /oauth/token, form-encoded, carrying the signature headers made with the key named in subject_token.
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_q8Zr2mX4k1Vb7nPw0sTeaccess_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). 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.
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;
}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 or ran out). On the agent’s side, signInAsAgent and requestIdJag throw refused when Pidgeon refuses the exchange (any of the errors below), 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) with the same signed exchange, and presents it there as a JWT bearer grant (RFC 7523).
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>- The ID-JAG is a JWT of type
oauth-id-jag+jwt, RS256 with Pidgeon’s published key, valid five minutes, never refreshed.subis the agent; it carriesaud,client_id,jtiand the agent’s claims. audienceis exactly one https issuer;resourcemust 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. |