API Reference

Every endpoint is prefixed with /api/v3/eak/. There are two groups, and they authenticate differently:

Endpoint group	Authentication
Delegation and tokens (10)	Access key signature: sign the request with your workspace AK/SK and put it in the Authorization header. Using the SDK is recommended (it signs automatically); if you call HTTP directly, you can reuse the SDK's exported buildAuthorization to build the signature
Workspaces and access keys (9)	Console session: for administrative operations

All responses are JSON. Error codes are listed at the end of the page.

Delegation and token endpoints

GET /api/v3/eak/runtime-config

Fetch the workspace runtime configuration (the endpoint addresses of each service). The SDK calls this automatically at initialization, so you rarely need it by hand.

POST /api/v3/eak/delegations

Start a delegation. mode decides the behavior: interactive returns an authorization link (user-level consent), silent issues immediately (organization-level consent — read Security considerations before using it).

Request field	Type	Required	Description
agent	string	✓	Agent identifier
scopes	string[]	✓	List of scopes being requested
userId	string	required for silent	ID of the user being delegated for (the SDK has moved to user: { id }; this parameter is the HTTP contract)
mode	silent | interactive	defaults to silent	Authorization mode
redirectUri	string	required for interactive	Where to return after authorization completes
state	string	required for interactive	Your business return state
expiresIn	number	optional	Token lifetime (seconds, 60–86400)

Response (silent): { mode: "silent", tokenType: "Bearer", delegationToken, delegateAgentToken, expiresIn, grantId, auditId }Response (interactive): { mode: "interactive", authorizationUrl, grantId, grantState, state, requestedScopes? }

Field names differ between HTTP and the SDK

In the HTTP response, the Delegate Token field is named delegationToken (delegateAgentToken is a legacy alias with the same value — use the former in new code). The SDK renames it to token and additionally provides grantedScopes — that is the SDK shape; neither key exists in the HTTP response. Mixing the two gets you undefined. For the mapping table, see SDK Reference.

POST /api/v3/eak/delegations/complete

Exchange the post-authorization callback parameters for a Delegate Token (SDK: completeDelegateToken).

Request field	Type	Description
grantId	string	Grant record ID
code	string	Authorization completion code
state	string	Authorization state

Response: a Delegate Token object, same shape as the silent response (mode / tokenType / delegationToken / delegateAgentToken / expiresIn / grantId / auditId).

Consent flow endpoints (called by the GenAuth-hosted authorization page)

The following four endpoints serve the page flow of interactive consent. If you use the hosted authorization page you never call them directly; if you build your own authorization experience, integrate against the request contracts below (the responses are flow-semantic objects — the interface Swagger is authoritative for their shape):

Endpoint	Purpose	Request fields
GET /api/v3/eak/delegations/:grantId/approval-context	Resolve the authorization login context (returns the login entry point and the request details)	query: grant_state, redirect_uri, state?
POST /api/v3/eak/delegations/auth/complete	Complete the OIDC login callback for the authorization page	code, state, redirectUri
POST /api/v3/eak/delegations/:grantId/approve	The user approves the authorization and a one-time callback code is generated (returns the return URL)	userId?, userPoolId?
POST /api/v3/eak/delegations/callback/consume	Consume the one-time code and issue the Delegate Token (the code is single-use; replays fail)	code, state

The response of callback/consume is a Delegate Token object (again: delegationToken is the token field name).

POST /api/v3/eak/token-exchange

Token exchange (RFC 8693 semantics): trade a Delegate Token for an access token for the target product.

Request field	Type	Required	Description
subjectToken	string	✓	The Delegate Token
resource	gumem | webagent	✓	The target product resource
scopes	string[]	optional	Product scopes needed for this exchange (must be a subset of the scopes already granted on the Delegate Token)

Response: { token, tokenType, expiresIn?, scope? } (the snake_case aliases access_token / token_type / expires_in are provided as well, so you can parse it the usual OAuth way). For the field structure of the access token, see Token and claim reference.

POST /api/v3/eak/genauth/admin-token

Obtain a management-plane access token (for server-side administrative operations, such as reading and writing the user directory). Response essentials: the management-plane accessToken and the user pool it applies to.

POST /api/v3/eak/delegations/introspect

Validate a Delegate Token online.

Request field	Type	Description
token	string	The Delegate Token

Response: when valid, { "active": true, ...all Delegate Token claims }; when invalid, expired, or malformed, always { "active": false } (the reason for failure is not disclosed).

Workspace and access key endpoints

A workspace is the isolation unit of the delegation model: it binds a user pool and product resources, and holds access keys.

Endpoint	Purpose
GET /api/v3/eak/tenants	List workspaces
POST /api/v3/eak/tenants	Create a workspace
GET /api/v3/eak/tenants/:eakTenantId	Workspace details
PATCH /api/v3/eak/tenants/:eakTenantId	Update a workspace
GET /api/v3/eak/tenants/:eakTenantId/credentials	List access keys
POST /api/v3/eak/tenants/:eakTenantId/credentials	Create an access key
POST /api/v3/eak/tenants/:eakTenantId/credentials/:accessKeyId/rotate	Rotate a key
PATCH /api/v3/eak/tenants/:eakTenantId/credentials/:accessKeyId	Enable/disable or update a key
DELETE /api/v3/eak/tenants/:eakTenantId/credentials/:accessKeyId	Delete a key

Create a workspace (POST /tenants) request fields: name (required), description?, genauthUserPoolId?, gumemProjectId?, webAgentTenantId?, delegationLoginCallbackUrl?, idempotencyKey?, status?.

Create / update access key request fields:

Field	Endpoint	Description
allowedScopes	create / update	Allowlist of scopes this key may request delegations for
allowedAgents	create / update	Allowlist of agents this key may delegate to
enable	update	Enable or disable the key (disabling takes effect immediately — see Revocation and emergency response)

Key security

The secret is returned only once, at creation and at rotation. Each workspace has a quota on the number of keys (see Limits). Always configure allowedScopes as the smallest possible set — it is the first gate on delegation (see Security considerations).

Error codes

Error responses carry code and requestId. At the HTTP layer, code is a dotted eak.* code, grouped into families by domain:

Code family	Typical codes	Common causes	HTTP status
anima.auth.*	anima.auth.invalid_signature, anima.auth.invalid_authorization_header, anima.auth.credential_disabled	Bad signature, malformed Authorization header, key already disabled	401
eak.delegation.*	eak.delegation.agent_not_allowed, eak.delegation.scope_not_allowed, eak.delegation.expires_in_invalid, eak.delegation.grant_invalid_or_expired, eak.delegation.user_not_bound	Agent or scope outside the key's allowlist, lifetime out of range, grant record invalid or expired, user not in the bound user pool	400 / 403
eak.token_exchange.*	eak.token_exchange.upstream_failed, eak.token_exchange.invalid_upstream_response	The upstream call during token exchange failed	502
anima.genauth.*	anima.genauth.userpool_binding_missing, anima.genauth.no_bound_users	The workspace has no user pool bound, or the pool has no users	400

The SDK's error codes are consolidated

The SDK folds the backend codes above into a small set of stable typed errors (auth.failed / delegation.required / permission_denied / token.expired / validation.failed / rate_limit.exceeded, and so on) and throws the matching error class. Over raw HTTP, branch on the eak.* code; with the SDK, branch on the error class — for the mapping, see SDK Reference.

Next steps

• Get started: Your first delegation in 30 minutes
• Reference: SDK Reference, Token and claim reference