​
Protocol Flow

The endpoints are called in this order:

​
Endpoint Map

MethodPathPurpose
GET/.well-known/ath-app.jsonNative service discovery
GET/.well-known/ath.jsonGateway discovery
POST/ath/agents/registerAgent registration
POST/ath/authorizeStart user authorization
GET/ath/callbackOAuth callback
POST/ath/tokenToken exchange
ANY/ath/proxy/{provider_id}/{path}API proxy
POST/ath/revokeToken revocation

​
POST /ath/agents/register

Request: 
{
  "agent_id": "https://agent.example/.well-known/agent.json",
  "agent_attestation": "<JWT>",
  "developer": { "name": "...", "id": "..." },
  "requested_providers": [{ "provider_id": "...", "scopes": ["..."] }],
  "purpose": "...",
  "redirect_uris": ["..."]
}
Response (201): 
{
  "client_id": "ath_...",
  "client_secret": "ath_secret_...",
  "agent_status": "approved",
  "approved_providers": [{ "provider_id": "...", "approved_scopes": [...], "denied_scopes": [...] }],
  "approval_expires": "2025-..."
}

​
POST /ath/authorize

Request: 
{
  "client_id": "ath_...",
  "agent_attestation": "<JWT>",
  "provider_id": "...",
  "scopes": ["..."],
  "state": "<random>",
  "user_redirect_uri": "...",
  "resource": "..."
}
Response (200): 
{
  "authorization_url": "https://...",
  "ath_session_id": "ath_sess_..."
}

​
POST /ath/token

Request: 
{
  "grant_type": "authorization_code",
  "client_id": "ath_...",
  "client_secret": "ath_secret_...",
  "agent_attestation": "<JWT with aud=token endpoint URL>",
  "code": "...",
  "ath_session_id": "ath_sess_..."
}
Response (200): 
{
  "access_token": "ath_tk_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "effective_scopes": ["..."],
  "provider_id": "...",
  "agent_id": "...",
  "scope_intersection": {
    "agent_approved": ["..."],
    "user_consented": ["..."],
    "effective": ["..."]
  }
}

​
ANY /ath/proxy//

Headers: 
Authorization: Bearer ath_tk_...
X-ATH-Agent-ID: https://agent.example/.well-known/agent.json  (optional)
Response: Upstream API response (forwarded).

​
POST /ath/revoke

Request: 
{
  "token": "ath_tk_...",
  "client_id": "ath_...",
  "client_secret": "ath_secret_..."
}
Response: Always 200 OK.