Agentic registration (auth.md)

abadge implements the WorkOS auth.md anonymous → user-claimed flow. An agent registers an unclaimed personal account on a person’s behalf and receives an abu_ personal API key immediately. The human then claims the account with a 6-digit code emailed to them, binding their verified email to the account. After the claim, the agent manages that person’s credentials through the normal items and profiles surface.

These endpoints live at the root of the API host (not under /v1) and are all unauthenticated. The issued credential is a standard personal API key (abu_): a management-surface session bound to the new account. It can never reach the agent-gated access surface — it cannot reveal or mount secret values.

Base URL

Environment	Base
Production	`https://api.abadge.io`
Local development	`http://localhost:8787`

Discovery

Discovery is two-hop, per RFC 9728. A 401 from any route carries a WWW-Authenticate header pointing at the protected-resource metadata, so an agent can bootstrap from a single failed request:

WWW-Authenticate: Bearer resource_metadata="https://api.abadge.io/.well-known/oauth-protected-resource"

Method	Path	Description
`GET`	`/.well-known/oauth-protected-resource`	Protected Resource Metadata (resource, authorization servers, supported scopes).
`GET`	`/.well-known/oauth-authorization-server`	Authorization Server Metadata, including the `agent_auth` block with the register / claim / revocation URIs.
`GET`	`/auth.md`	Markdown skill manifest an agent can read to learn the flow.

Example: oauth-authorization-server metadata

{
  "issuer": "https://api.abadge.io/",
  "authorization_servers": ["https://api.abadge.io/"],
  "scopes_supported": ["abadge:account.read", "abadge:account.manage"],
  "bearer_methods_supported": ["header"],
  "agent_auth": {
    "skill": "https://api.abadge.io/auth.md",
    "register_uri": "https://api.abadge.io/agent/auth",
    "claim_uri": "https://api.abadge.io/agent/auth/claim",
    "revocation_uri": "https://api.abadge.io/agent/auth/revoke",
    "identity_types_supported": ["anonymous"],
    "anonymous": { "credential_types_supported": ["api_key"] }
  }
}

The flow

POST /agent/auth provisions an unclaimed personal account (a placeholder-email owner, an org, and a default server_managed profile) and returns an abu_ credential plus a clm_ claim token. The credential authenticates immediately but the account stays inert until it is claimed.

Start the claim

POST /agent/auth/claim with the human’s email. abadge emails them a 6-digit code. The agent asks the human for that code.

Complete the claim

POST /agent/auth/claim/complete with the code. abadge binds the human’s verified email to the account in place and upgrades the credential’s scopes.

Use the credential

Send Authorization: Bearer abu_.... The agent can now read and manage the person’s vault through the normal management surface.

Register

string

default:"anonymous"

Identity type. Only anonymous is supported.

string

default:"api_key"

Credential type. Only api_key is supported.

curl -X POST https://api.abadge.io/agent/auth \
  -H "Content-Type: application/json" \
  -d '{ "type": "anonymous", "requested_credential_type": "api_key" }'

string

Opaque registration identifier.

string

Always anonymous.

string

Always api_key.

string

The abu_ personal API key. Shown once — store it now.

null

Personal API keys do not expire on their own; the owner revokes them.

string[]

Pre-claim scopes (abadge:account.read).

string

The URL to call for the claim step.

string

A clm_ token. Pass it to both claim calls. Expires after 24 hours.

string

ISO 8601 expiry of the claim token.

string[]

Scopes granted after a successful claim (abadge:account.read, abadge:account.manage).

Start the claim

string

required

The clm_ token from registration.

string

required

The human owner’s email. abadge sends a 6-digit code here.

curl -X POST https://api.abadge.io/agent/auth/claim \
  -H "Content-Type: application/json" \
  -d '{ "claim_token": "clm_...", "email": "[email protected]" }'

string

The registration being claimed.

string

Identifier for this claim attempt.

string

Always initiated.

string

ISO 8601 expiry of the emailed code (10 minutes).

Complete the claim

string

required

The same clm_ token.

string

required

The 6-digit code the human received by email.

curl -X POST https://api.abadge.io/agent/auth/claim/complete \
  -H "Content-Type: application/json" \
  -d '{ "claim_token": "clm_...", "otp": "123456" }'

string

The claimed registration.

string

Always claimed. The credential’s scopes are upgraded in place.

Limits and lifetimes

Constraint	Value
Rate limit	60 requests / minute / IP across `/agent/auth*`
Claim token TTL	24 hours
OTP TTL	10 minutes
Max OTP attempts	5 (then restart the claim)
Unclaimed account GC	Removed after 24 hours if never claimed

Errors

This surface returns the standard { code, message, hint, meta } error envelope. The auth.md-specific codes are:

Code	HTTP	Meaning
`INVALID_CLAIM_TOKEN`	400	The `claim_token` is unknown, already used, or malformed.
`CLAIM_TOKEN_EXPIRED`	400	The `claim_token` passed its 24-hour TTL; register again.
`OTP_NOT_REQUESTED`	400	`claim/complete` called before `claim`.
`OTP_INVALID`	400	The supplied code is wrong.
`OTP_EXPIRED`	400	The code passed its 10-minute TTL; start the claim again.
`OTP_ATTEMPTS_EXCEEDED`	400	Too many wrong codes (max 5); restart the claim.
`CLAIM_EMAIL_IN_USE`	409	The email already maps to an existing account.
`CLAIM_ALREADY_COMPLETED`	409	The claim was already completed.

Revocation

There is no agent-facing revoke. The account owner revokes the agent’s credential from the dashboard; a revoked credential then returns 401.

Introduction

Organizations

Members & invites

API keys

Profiles

Items

Agents

Agent sessions

Permissions

Access

Audit

System

SDK

Agentic registration (auth.md)

Base URL

Discovery

The flow

Register

Start the claim

Complete the claim

Limits and lifetimes

Errors

Revocation

​Base URL

​Discovery

​The flow

​Register

​Start the claim

​Complete the claim

​Limits and lifetimes

​Errors

​Revocation

Base URL

Discovery

The flow

Register

Start the claim

Complete the claim

Limits and lifetimes

Errors

Revocation