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_q8Zr2mX4k1Vb7nPw0sTe

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

errorWhen
invalid_requestA wrong subject_token_type or requested_token_type, not exactly one audience, or no client_id for an ID-JAG.
invalid_grantThe 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_targetThe 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_deniedThe site has used its free agent sign-ins this month and usage billing is off.