Agents quickstart

Outcome: an agent identity that can mint a client_credentials token and call one protected route. About five minutes after Agents access is approved.

Sales-gated. Agents stays locked until access is approved. Use Request access on the locked landing or Support. Do not put a human cookie or PAT in the agent runtime.

0. Prerequisites

• An Authdog tenant, project, and environment.
• Approved access to Agents in that environment.
• A token endpoint from the environment OIDC metadata (/oauth2/token).

1. Register an agent

In the console, open Agents (/dashboard/agents):

1. New agent → Create new agent identity.
2. Name it. Optional: scopes (mcp:invoke), allowed tools (* or globs).
3. Copy the client ID and client secret. The secret is shown once.

This provisions a confidential OIDC client and a trust-store row whose subject is that client ID.

REST equivalent (after you have a management token):

POST /v1/tenants/{tenantId}/environments/{environmentId}/mcp/trust-store

The wizard is the path that also creates the OIDC client. REST registers a subject that already authenticates.

2. Exchange credentials for a 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"

You get access_token, token_type, expires_in. No refresh token. Repeat the exchange before expiry.

A revoked agent whose subject is this client_id gets 401 on this call. Tokens already issued stay valid until expires_in unless the resource server runs trust-store enforce.

3. Call a protected route

Authorization: Bearer <access_token>

For an HTTP API, use a backend SDK require_auth gate (Express, FastAPI). For MCP, run examples/mcp-auth-sample with MCP_TRUST_STORE_MODE=enforce and MCP_AUTHZ_MODE=enforce. @authdog/mcp-sdk is source-only (packages/mcp-sdk), not on npm.

4. Verify

• Token exchange without credentials → 401.
• GET the protected route without a bearer → 401.
• With the bearer → the caller is the agent, not a human session.

Next

• Agents: verify, revoke, pin, activity.
• Machine identity: M2M project vs Agents vs service account vs PAT.
• AI agent security: same primitives, longer form.
• MCP security: protect your MCP server.