Agent Auth (OAuth 2.1)

OAuth 2.1 identity service for autonomous agents. Supports client credentials flow, token introspection (RFC 7662), revocation (RFC 7009), and delegated token exchange for agent-to-agent authentication.

Base path: /api/v1/cloud/auth

POST /clients

Create an OAuth 2.1 client for a registered agent. The client_secret is returned only once.

curl -X POST https://api.ainative.studio/api/v1/cloud/auth/clients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_registration_id": "agent-a1b2c3d4e5f6",
    "scopes": ["agent:read", "agent:write", "memory:read", "memory:write"],
    "token_ttl_seconds": 3600
  }'

Response (201):

{
  "id": "client-uuid",
  "client_id": "agt_abc123def456",
  "client_secret": "sk_agent_xxxxxxxxxxxx",
  "scopes": ["agent:read", "agent:write", "memory:read", "memory:write"],
  "token_ttl_seconds": 3600
}

POST /token

Client credentials grant. Exchange client_id + client_secret for an access token.

curl -X POST https://api.ainative.studio/api/v1/cloud/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=agt_abc123&client_secret=sk_agent_xxx&scope=agent:read memory:read"

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "agent:read memory:read"
}

POST /token/introspect

Validate a token per RFC 7662. Use this to verify tokens from other agents.

curl -X POST https://api.ainative.studio/api/v1/cloud/auth/token/introspect \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJ..."}'

Response:

{
  "active": true,
  "client_id": "agt_abc123def456",
  "scope": "agent:read memory:read",
  "exp": 1712200000,
  "iat": 1712196400
}

POST /token/revoke

Revoke a token per RFC 7009.

curl -X POST https://api.ainative.studio/api/v1/cloud/auth/token/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJ..."}'

POST /token/delegate

Delegated token exchange for agent-to-agent auth. Agent A can request a scoped token to act on behalf of a user when calling Agent B.

curl -X POST https://api.ainative.studio/api/v1/cloud/auth/token/delegate \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_agent_id": "agent-target-xyz",
    "scopes": ["memory:read"],
    "ttl_seconds": 600
  }'

Response:

{
  "delegated_token": "eyJ...",
  "expires_in": 600,
  "target_agent_id": "agent-target-xyz",
  "scopes": ["memory:read"]
}

Available Scopes

Scope	Description
agent:read	Read agent registry and catalog
agent:write	Register, update, deploy agents
memory:read	Recall memories, search vectors
memory:write	Store memories, add vectors
a2a:message	Send A2A messages
deploy:manage	Create and scale deployments