Authentication

Exchange agent credentials for JWT

Returns a short-lived EdDSA-signed JWT (access_token). Standard claims include sub (agent:<uuid>), org, scopes, vault_ids, optional intents_api_enabled, optional shroud_enabled, optional llm_token_billing / stripe_customer_id when org LLM billing is on.

When shroud_enabled is true, the JWT payload may include shroud_config: a JSON object mirroring the agent row in Vault (same shape as ShroudConfig on GET /v1/agents/{id}). Shroud (TEE proxy) decodes this on each LLM request and runs PolicyEngine after the global inspection pipeline so per-agent limits and threat block actions apply without a separate policy fetch. Re-exchange the agent token after changing shroud_config so the JWT is fresh.

User JWTs from password, API key, or device flow do not include shroud_config.

Router keys. An sk-shroud-v1-… key (minted at POST /v1/agents/{agent_id}/router-keys) is exchanged key-only — send api_key alone, no agent_id. The token carries a router_key claim ({id, max_concurrent_streams?, spend_cap_micro_usd?}), lives at most 60 s (revocation SLA), and is only issued for Shroud-enabled agents. Revoked keys get 401.

post/v1/auth/agent-token

Request

  • Base URL: https://api.1claw.co
  • URL: https://api.1claw.co/v1/auth/agent-token
  • Auth: none required

Request body

agent_idstring uuid

Optional for api_key agents (ocv_ keys auto-resolve from their prefix). Required for OIDC and mTLS agents, which have no key to look up by.

api_keystring

The ocv_ key, for auth_method api_key.

oidc_tokenstring

Token minted by the agent's OIDC provider, for auth_method oidc_client_credentials. Verified against the issuer and audience on the agent record, so nothing long-lived is stored where the agent runs.

dpop_jwkobject

Optional DPoP public key (JWK) binding the issued JWT to a client keypair.

Response

Agent JWT issued

access_tokenstring required
token_typestring required
expires_ininteger
refresh_tokenstring
mfa_requiredboolean
mfa_tokenstring
mfa_method'totp' | 'passkey'
agent_idstring uuid

Agent token exchange only — the resolved agent id.

vault_idsstring[]

Agent token exchange only — vaults the agent is bound to.

Changes

No recorded changes to this operation across all 1 revision of this API.