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 normalizes it to token. Neither the silent HTTP response nor the SDK result contains the effective scope list. Call /delegations/introspect and read active and scope when you need validity and the actually granted boundary. For the mapping table, see SDK Reference.
In an interactive response, state is a compatibility alias of the server-generated grantState; it does not echo the request's business state. Correlate the grant by verifying that the authorization URL query grant_id equals response grantId, then save grantId and your business state on the server, keyed by grantState. After consent, the callback to redirectUri carries code, state (your business state), and grant_state (equal to grantState), but no grantId.
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: the grantId from the create response, saved on your server (the callback does not carry it) |
code | string | The callback's one-time code |
state | string | The callback's grant_state (equal to grantState from the create response); not your business 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 |
|---|---|---|---|
eak.auth.* | eak.auth.invalid_signature, eak.auth.invalid_authorization_header, eak.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 |
eak.genauth.* | eak.genauth.userpool_binding_missing, eak.genauth.no_bound_users | The workspace has no user pool bound, or the pool has no users | 400 |
The SDK provides typed error classes
The SDK maps HTTP status and error semantics to typed errors such as QoniAuthError, QoniPermissionDeniedError, and QoniTokenExpiredError. When the server returns an eak.* code, error.code still preserves that original value. Handle broad cases by error class, then inspect error.code only when you need a specific backend reason — fields and classes: SDK Reference.
Next steps
- Get started: Your first delegation in 30 minutes
- Reference: SDK Reference, Token and claim reference