title: "Agent Auth" description: "MachineMail's authorization server: OAuth sign-in with PKCE and client registration for apps and MCP clients, and the auth.md agent onboarding endpoints." canonical: "https://machinemail.dev/docs/reference/api/agent-auth"

Agent Auth

MachineMail's authorization server: OAuth sign-in with PKCE and client registration for apps and MCP clients, and the auth.md agent onboarding endpoints.

Source: https://machinemail.dev/docs/reference/api/agent-auth

These endpoints implement the auth.md agent onboarding protocol. They use OAuth-style error bodies ({"error": "...", "error_description": "..."}) instead of the uniform MachineMail error envelope.

JSON Web Key Set

GET /.well-known/jwks.json

The service’s public signing key (RFC 7517). Verifies the identity assertions and access tokens this service issues.

Authentication: None.

Response

200 JWKS (application/json)

Headers:

Errors

Example

curl "https://api.machinemail.dev/.well-known/jwks.json"

{
  "keys": [
    {
      "key": "value"
    }
  ]
}

OAuth Authorization Server Metadata

GET /.well-known/oauth-authorization-server

RFC 8414 plus the auth.md agent_auth block. identity_types_supported lists the registration types MachineMail accepts.

Authentication: None.

Response

200 The metadata (application/json)

Errors

Example

curl "https://api.machinemail.dev/.well-known/oauth-authorization-server"

{
  "resource": "string",
  "authorization_servers": ["string"],
  "scopes_supported": ["inboxes.read"],
  "bearer_methods_supported": ["string"],
  "issuer": "string",
  "authorization_endpoint": "string",
  "token_endpoint": "string",
  "registration_endpoint": "string",
  "revocation_endpoint": "string",
  "device_authorization_endpoint": "string",
  "jwks_uri": "https://example.com",
  "service_documentation": "string",
  "grant_types_supported": ["string"],
  "response_types_supported": ["string"],
  "response_modes_supported": ["string"],
  "code_challenge_methods_supported": ["string"],
  "token_endpoint_auth_methods_supported": ["string"],
  "revocation_endpoint_auth_methods_supported": ["string"],
  "client_id_metadata_document_supported": false,
  "authorization_response_iss_parameter_supported": false,
  "agent_auth": {
    "skill": "string",
    "identity_endpoint": "string",
    "claim_endpoint": "string",
    "events_endpoint": "string",
    "identity_types_supported": ["anonymous"],
    "identity_assertion": {
      "assertion_types_supported": ["string"]
    },
    "events_supported": ["string"]
  }
}

OAuth Protected Resource Metadata

GET /.well-known/oauth-protected-resource

RFC 9728. Referenced by the WWW-Authenticate header on 401 responses from /v0 and /mcp. On the MCP host (mcp.machinemail.dev) it describes the MCP server there, the same as the path-suffixed form.

Authentication: None.

Response

200 The metadata (application/json)

Errors

Example

curl "https://api.machinemail.dev/.well-known/oauth-protected-resource"

{
  "resource": "string",
  "authorization_servers": ["string"],
  "scopes_supported": ["inboxes.read"],
  "bearer_methods_supported": ["string"],
  "resource_name": "string",
  "resource_logo_uri": "https://example.com",
  "resource_documentation": "string"
}

OAuth Protected Resource Metadata (Path-Suffixed)

GET /.well-known/oauth-protected-resource/{path}

RFC 9728 metadata for a resource at a path, for example /.well-known/oauth-protected-resource/mcp. resource is <issuer>/<path>; everything else is the same as the root document. path may contain slashes. On the MCP host (https://mcp.machinemail.dev/mcp) only mcp is served and resource is that URL; authorization_servers still names the issuer.

Authentication: None.

Path parameters

Response

200 The metadata (application/json)

Errors

Example

curl "https://api.machinemail.dev/.well-known/oauth-protected-resource/mcp"

Receive Security Event Token

POST /agent/event/notify

RFC 8935 push delivery from a trusted agent provider. The body is a signed SET (typ: secevent+jwt) with aud equal to the issuer, a unique jti, and an events claim containing https://schemas.workos.com/events/agent/auth/identity/assertion/revoked. Every registration for that (iss, sub) is revoked.

Authentication: None.

Request body

Content type: application/secevent+jwt. Required.

Type: string

Response

202 Accepted (empty body)

Errors

Example

curl -X POST "https://api.machinemail.dev/agent/event/notify" \
  -H "Content-Type: application/secevent+jwt" \
  --data-binary @body

Register Agent Identity

POST /agent/identity

Dispatches on type (auth.md). No API key is ever returned.

anonymous returns a pre-claim identity_assertion and the sandbox inbox (one ephemeral inbox on the shared domain); exchange the assertion at /oauth2/token for an access token.

service_auth withholds the assertion and returns a claim block until the named user (login_hint) confirms.

identity_assertion verifies an ID-JAG from a trusted provider. When the verified email belongs to an existing user it answers 401 interaction_required with a claim_token and claim block; when auth_time is too old, 401 login_required with max_age. Both set WWW-Authenticate: AgentAuth error="...".

Registration is rate limited per requester (an IPv4 address, or an IPv6 /64) and overall: 429 rate_limited with Retry-After. anonymous and service_auth share a cap per requester of at most 1 per rolling hour and 3 per rolling 24 hours (an IPv6 /48, all its /64s together, at most 10 per rolling 24 hours), and a platform-wide cap of about 100 per rolling hour and 1000 per rolling 24 hours. anonymous is also refused while about 500 unclaimed sandbox inboxes are live (Sandbox capacity is full right now); a claimed or expired registration frees its place.

Registrations from a network that was blocked for abuse are refused with 403 registration_blocked (no Retry-After: retrying does not help).

identity_assertion with a verified email that matches no account creates a new organization; when that email is a disposable email address it is refused with 403 disposable_email_not_allowed (param email): MachineMail doesn’t accept disposable addresses for new accounts.

Authentication: None.

Request body

Content type: application/json. Required.

Response

200 Registered (application/json)

Headers:

Errors

Example

curl -X POST "https://api.machinemail.dev/agent/identity" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "anonymous",
  "name": "Production"
}'

{
  "registration_id": "string",
  "agent_id": "string",
  "registration_type": "anonymous",
  "identity_assertion": "string",
  "assertion_expires": "2026-10-01T12:00:00.000Z",
  "scopes": ["inboxes.read"],
  "pre_claim_scopes": ["inboxes.read"],
  "post_claim_scopes": ["inboxes.read"],
  "claim_url": "https://example.com",
  "claim_token": "string",
  "claim_token_expires": "2026-10-01T12:00:00.000Z",
  "claim": {
    "user_code": "string",
    "verification_uri": "https://example.com",
    "expires_in": 1,
    "interval": 1
  },
  "inbox": {
    "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
    "inbox_id": "agent@machinemail.dev",
    "email": "agent@machinemail.dev",
    "display_name": "Support Agent",
    "client_id": "my-client-id",
    "status": "active",
    "metadata": {
      "key": "value"
    },
    "updated_at": "2026-10-01T12:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z",
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "ephemeral": false,
    "ttl_seconds": 1,
    "expires_at": "2026-10-01T12:00:00.000Z",
    "created_by": "api"
  }
}

Start Claim Ceremony

POST /agent/identity/claim

Called by the agent. Protocol form: {claim_token, email?}. Alternative: {agent_id} (or registration_id) with the registration’s access token or identity assertion as Authorization: Bearer.

Returns a 6-digit user_code and a verification_uri to show the human, who completes the claim in the dashboard (POST /auth/claim). The agent then polls /oauth2/token with the claim grant. Calling it again starts a fresh attempt.

Authentication: None.

Request body

Content type: application/json. Required.

Send claim_token (and optionally email), or agent_id with Bearer proof.

Response

200 Claim attempt started (application/json)

Headers:

claim_attempt is a ClaimBlock:

Errors

Example

curl -X POST "https://api.machinemail.dev/agent/identity/claim" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "agent@machinemail.dev"
}'

{
  "registration_id": "string",
  "agent_id": "string",
  "claim_attempt_id": "string",
  "status": "initiated",
  "expires_at": "2026-10-01T12:00:00.000Z",
  "claim_attempt": {
    "user_code": "string",
    "verification_uri": "https://example.com",
    "expires_in": 1,
    "interval": 1
  },
  "user_code": "string",
  "verification_uri": "https://example.com",
  "expires_in": 1,
  "interval": 1
}

Agent Onboarding Document

GET /auth.md

Markdown instructions for agents (auth.md protocol): how to register, claim and authenticate. Lists the registration types MachineMail accepts.

Authentication: None.

Response

200 auth.md (text/markdown)

Headers:

Errors

Example

curl "https://api.machinemail.dev/auth.md"

Authorization Endpoint

GET /oauth2/authorize

OAuth 2.1 authorization code grant, opened in the person’s browser by an app or MCP client. Requires PKCE (code_challenge with code_challenge_method=S256) and the RFC 8707 resource: the MCP server’s URL (https://mcp.machinemail.dev/mcp, or the legacy <issuer>/mcp; a token for either works on both MCP endpoints), or <issuer>/ for the REST API and MCP.

A valid request is stored for 10 minutes and the browser is sent to the dashboard consent page, https://machinemail.dev/connect?request=<id> (sign-in first when needed). The person sees the client, where the response goes and the scopes, chooses the whole organization, one pod or one inbox, and approves or denies. The browser then returns to redirect_uri with code (single use, 2 minutes) or error=access_denied, plus state and iss (RFC 9207).

Errors: an unknown client_id, a redirect_uri the client did not register, or too many requests from one address (rate_limited) is shown on /connect?error=... and never redirected. Every other error goes back to redirect_uri as error (invalid_request, unsupported_response_type, invalid_scope, invalid_target) with error_description, state and iss.

Authentication: None.

Query parameters

Response

302 To the consent page, to redirect_uri with an error, or to the error page.

Headers:

Errors

Example

curl "https://api.machinemail.dev/oauth2/authorize"

Register OAuth Client

POST /oauth2/register

RFC 7591 Dynamic Client Registration for apps and MCP clients. Public clients by default (token_endpoint_auth_method none, no secret). A client that asks for client_secret_post or client_secret_basic is confidential: the response carries its client_secret (shown once, never expires: client_secret_expires_at 0) and the token and revocation endpoints then require it, by either method. Any other method is replaced with none. Every authorization uses PKCE, confidential or not. No registration access token is issued (registrations cannot be read or changed later; register again instead).

Clients that can host a Client ID Metadata Document should use its https URL as client_id instead of registering (client_id_metadata_document_supported in the server metadata). Registrations never used for an authorization are deleted after 7 days.

Rate limited per client IP and overall: 429 rate_limited with Retry-After.

Authentication: None.

Request body

Content type: application/json. Required.

RFC 7591 client metadata. Unknown members are ignored.

Response

201 Registered (application/json)

Headers:

Errors

Example

curl -X POST "https://api.machinemail.dev/oauth2/register" \
  -H "Content-Type: application/json" \
  -d '{
  "redirect_uris": [
    "string"
  ]
}'

{
  "client_id": "my-client-id",
  "client_id_issued_at": 1,
  "client_name": "string",
  "client_uri": "https://example.com",
  "logo_uri": "https://example.com",
  "redirect_uris": ["string"],
  "grant_types": ["string"],
  "response_types": ["string"],
  "token_endpoint_auth_method": "none",
  "client_secret": "string",
  "client_secret_expires_at": 1,
  "application_type": "native",
  "scope": "string",
  "software_id": "string",
  "software_version": "string"
}

Revoke Token

POST /oauth2/revoke

RFC 7009. Idempotent: unknown tokens succeed too. Revoking an access token ends only that token; revoking a refresh token ends its whole grant (the app is disconnected); revoking an identity assertion (tried first with token_type_hint=identity_assertion) revokes the whole registration. A confidential client that names itself authenticates as at the token endpoint (401 invalid_client otherwise). Form-encoded or JSON bodies.

Authentication: None.

Request body

Content type: application/x-www-form-urlencoded or application/json. Required.

Response

200 Revoked (empty body)

Errors

Example

curl -X POST "https://api.machinemail.dev/oauth2/revoke" \
  --data-urlencode "token=string"

Token Endpoint

POST /oauth2/token

The token endpoint of the MachineMail authorization server. Public clients (token_endpoint_auth_method none: URL client IDs and registrations without a secret) send client_id in the body. Confidential clients (registered with client_secret_post or client_secret_basic) authenticate with HTTP Basic or client_secret in the body, either way; a missing or wrong secret is 401 invalid_client. PKCE applies to every client.

authorization_code redeems a code from /oauth2/authorize with its PKCE code_verifier and returns an access token bound to the requested resource and a refresh_token. refresh_token returns a new access token and a new refresh token, and the old one stops working: presenting it again within 60 seconds returns the same new refresh token (concurrent refreshes and retries are safe), later it revokes the whole grant (reuse detection). A code redeemed twice also revokes its grant.

urn:ietf:params:oauth:grant-type:device_code is the mm login device grant (same as /auth/cli/device/token; the response is a CliDeviceTokenResponse with an API key).

urn:ietf:params:oauth:grant-type:jwt-bearer (RFC 7523) exchanges an auth.md identity_assertion for an access token. urn:workos:agent-auth:grant-type:claim is polled with a claim_token until the human finishes the claim, then returns an access token and the post-claim identity_assertion.

Form-encoded (RFC 6749) or JSON bodies.

Authentication: None.

Request body

Content type: application/x-www-form-urlencoded or application/json. Required.

Response

200 Access token (an API key for the device grant) (application/json)

Headers:

Type: TokenResponse | CliDeviceTokenResponse

Errors

Example

curl -X POST "https://api.machinemail.dev/oauth2/token" \
  --data-urlencode "grant_type=string"

{
  "access_token": "string",
  "token_type": "Bearer",
  "expires_in": 1,
  "scope": "string",
  "refresh_token": "string",
  "identity_assertion": "string",
  "assertion_expires": "2026-10-01T12:00:00.000Z"
}