Agent frameworks

Authdog is the identity provider. The framework keeps its own auth hook. Register an agent, mint a short-lived bearer with client_credentials, and verify that bearer at the hook before the agent, tool, or graph runs.

Each hook is grouped under AI. The group has pages for the auth boundary, machine credentials, tool checks, and what you put in the prompt.

Runnable copies live in authdog/agents-samples. Copy one folder. Each folder is its own project.

Which path

Where the hook is

Rows marked "Sample planned" describe the hook. The folder is not in the repository yet, and the page does not pin a package version. subject_if_accepted and subjectIfAccepted in those snippets are the sample's userinfo helper. They are not framework APIs. They return the subject, or nothing when the bearer is missing or rejected.

Register the caller

In the console, open Agents → Create new agent identity. Copy the client id and client secret. The secret is shown once.

The protected process takes the environment public key (pk_...) from Project settings. That key selects the identity host. It does not mint tokens.

Keep the client secret in the process that calls the token endpoint. Put the access token on the HTTP request. Leave both out of prompts, graph state, and logs.

The Agents module is sales-gated. Until access is approved, an M2M application issues the same client_credentials grant. Keep a development token off your production API.

Mint the bearer

Read token_endpoint from the environment discovery document. Authdog's path is /oauth2/token.

curl -X POST "$TOKEN_ENDPOINT" \
  -u "$AUTHDOG_CLIENT_ID:$AUTHDOG_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials"

The response carries access_token, token_type (Bearer), and expires_in. There is no refresh token. Repeat the exchange before expiry.

Send it as Authorization: Bearer <access_token>.

What verification returns

require_auth and fetch_user_data both check the bearer with the environment userinfo endpoint. The public key chooses that host. A missing bearer, a userinfo rejection, or a payload with no subject is 401. An accepted payload looks like the samples' stand-in:

{"meta": {"code": 200}, "user": {"id": "agent_1"}}

The samples read user.id, then user.sub, and return that string. Where the framework has a scope field, they record agent:invoke.

Eve is the exception on this page: it verifies the JWT with discovery instead of calling userinfo. The subject still has to be the one in that token. See Eve checks the JWT.

After the subject is known

The samples stop once the subject is known. A 200 from whoami means userinfo accepted the bearer. It does not mean the agent may call every tool.

The Agents registry is the next check on that subject:

Apply authorization after the identity check when the API is yours.

Acting for a person

The framework hook stays the same. Replace the client_credentials access token with an RFC 8693 token. sub stays the user. act names the agent.

{
  "sub": "<user id>",
  "act": { "sub": "client:<agent client_id>" }
}

Put that token in the Authorization header, or in the OpenAI Agents `Caller.token`. Grant token exchange on the agent in Agents. The delegation sample reads a token whose subject is the person. The other samples mint a token whose subject is the agent client.

One token, three callers

Mint once. Present that bearer to each userinfo gate. Run one sample at a time, or bind the ports below so they do not share 8000.

TOKEN=$(curl -s -X POST "$TOKEN_ENDPOINT" \
  -u "$AUTHDOG_CLIENT_ID:$AUTHDOG_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  | python -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

LangGraph, from langgraph/python with PK_AUTHDOG set:

uvicorn server:create_app --factory --port 8001
curl -s -X POST http://127.0.0.1:8001/invoke \
  -H "Authorization: Bearer $TOKEN"

The JSON reply is {"reply":"subject:<id>"}. The same call without the header is 401 and the body has no subject:.

MCP, from mcp/python with PK_AUTHDOG set. The verifier reads this header. POST /mcp without it is 401. The sample's whoami tool returns the subject:

uvicorn server:create_app --factory --port 8002
curl -s -D - -o /dev/null -X POST http://127.0.0.1:8002/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

OpenAI Agents, from openai-agents/python. The route is the gate. The tool only attaches the header. OPENAI_API_KEY is required for Runner.run. pytest does not need it.

uvicorn tool_api:create_app --factory --port 8003
export WHOAMI_URL=http://127.0.0.1:8003/whoami
export AUTHDOG_ACCESS_TOKEN="$TOKEN"

context=Caller(token=os.environ["AUTHDOG_ACCESS_TOKEN"])

GET /whoami with the bearer returns {"subject":"<id>"}.

Eve checks the JWT

Eve does not call userinfo. oidc() verifies the bearer as a JWT against the issuer discovery document: signature, issuer, expiry, and audience. Agent access tokens for the environment are JWTs. Set AUTHDOG_ISSUER to the token's iss and AUTHDOG_AUDIENCE to its aud. The Eve process reads neither the client secret nor PK_AUTHDOG.

npx eve dev listens on port 2000 unless PORT is set.

curl -s -D - -o /dev/null -X POST http://127.0.0.1:2000/eve/v1/session \
  -H "Authorization: Bearer $TOKEN"

A session request with no bearer is 401. The health route stays public.

Python gate

A2A, MCP, LangGraph, and the OpenAI Agents sample import require_auth or fetch_user_data from the Python SDK in authdog/web-sdk. That package is installed from commit afad543932541a9e9d3c891421151509d04b49b2 in each sample's requirements.txt. pip install authdog-fastapi on the public index is a different name and is not the install those samples use.

Eve verifies the JWT with Eve's own oidc() helper and the issuer discovery document.

Related