auth.md agent access

Whagons publishes an auth.md-style agent authentication service at:

https://gon.whagons.com/auth.md

auth.md is an open, Markdown-based discovery pattern for agents. Whagons currently supports a user-claimed service_auth flow: an agent starts with the user's email address, and that signed-in Whagons user approves the agent for a selected tenant.

Beta

Agent authentication is being actively refined. Build clients to read discovery metadata at runtime and handle unknown fields and recoverable errors.

Security model

Anonymous pre-claim access is not supported.
The approving user must sign in to Whagons.
The claim is bound to the email address supplied by the agent.
The user chooses the tenant when more than one is available.
The agent acts on behalf of that user and never gains more product access than the user currently has.
Registrations, claims, token issuance, use, and revocation are auditable.
Raw tokens are stored as hashes by Whagons.

Discovery endpoints

Resource	URL
Human- and agent-readable guide	`https://gon.whagons.com/auth.md`
Protected resource metadata	`https://gon.whagons.com/.well-known/oauth-protected-resource`
Authorization server metadata	`https://gon.whagons.com/.well-known/oauth-authorization-server`
Identity registration	`POST https://gon.whagons.com/agent/identity`
Token exchange	`POST https://gon.whagons.com/oauth2/token`
Token revocation	`POST https://gon.whagons.com/oauth2/revoke`

Fetch metadata instead of hard-coding token lifetimes or supported grants.

Supported scopes

Scope	Allows
`ext:read`	Read tenant reference data and visible task data.
`ext:tasks:write`	Perform documented task writes allowed by the approving user's current Whagons permissions.

If the request contains no recognized scope, Whagons defaults to ext:read. Unknown scopes are ignored.

1. Register an identity

curl -X POST "https://gon.whagons.com/agent/identity" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "service_auth",
    "login_hint": "operator@example.com",
    "name": "Guest request triage agent",
    "scopes": ["ext:read", "ext:tasks:write"]
  }'

The response contains secrets and user-facing values:

{
  "type": "service_auth",
  "claim_token": "whg_claim_…",
  "claim_attempt_token": "whg_claim_attempt_…",
  "user_code": "123456",
  "verification_uri": "https://app.whagons.com/auth/agent-claim",
  "verification_uri_complete": "https://app.whagons.com/auth/agent-claim?claim_attempt_token=…",
  "expires_in": 600,
  "interval": 5,
  "scopes": ["ext:read", "ext:tasks:write"]
}

The response-supplied verification URI is authoritative. Show the six-digit user_code to the user and open or share verification_uri_complete.

Keep claim_token and claim_attempt_token private. The user only needs the verification link and code.

2. Wait for user approval

The user signs in, confirms the displayed code, and chooses a tenant. Claims expire after ten minutes.

The agent may poll the token endpoint at the response's interval, currently five seconds:

curl -X POST "https://gon.whagons.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:workos:agent-auth:grant-type:claim" \
  --data-urlencode "claim_token=$WHAGONS_CLAIM_TOKEN"

While approval is pending, the service returns:

{
  "error": "authorization_pending",
  "error_description": "User claim is still pending"
}

Respect the polling interval and stop when the claim expires or returns a terminal error.

3. Receive a token

After approval, the token exchange returns:

{
  "access_token": "whg_agent_…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "ext:read ext:tasks:write",
  "identity_assertion": "eyJ…"
}

The access token is short-lived and must be sent only in the Authorization header. The identity assertion is also time-limited; clients should use discovery metadata and be prepared to restart the claim flow when renewal is no longer accepted.

4. Re-exchange an assertion

While the latest identity assertion is valid, exchange it with the JWT bearer grant:

curl -X POST "https://gon.whagons.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion=$WHAGONS_IDENTITY_ASSERTION"

Each successful response includes a new access token and identity assertion. If renewal fails, do not loop indefinitely; start a new user claim.

5. Revoke a token

curl -X POST "https://gon.whagons.com/oauth2/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=$WHAGONS_AGENT_TOKEN"

Revocation is idempotent and returns success even when the token is already unknown or revoked.

Protocol reference

Whagons follows an early auth.md-style flow and publishes its implemented behavior through its own discovery documents. For the broader protocol background, see the auth.md project.

Continue with the user claim flow or call the Whagons API.

On this page