Keys
List, create, and revoke the keys that act for your account.
| Operation | Request |
|---|---|
| List account keys | GET /v1/keys |
| Create account key | POST /v1/keys |
| Revoke account key | DELETE /v1/keys/{id} |
List account keys
GET /v1/keys · listAccountKeys
List this account's working keys without secrets. Sign-in keys are newest first; expired/revoked keys are omitted. There is no pagination; API key ordering is unspecified.
Sign-in: a bearer credential in the Authorization header.
appKeyManagementBearer: An account-service-issued live app session (sess_) or sign-in key (oa_sk_). The account service validates it on every request. Cookies and oak_ API keys cannot manage these keys. A sign-in key can create and revoke other sign-in keys for the same account, including itself.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
kind | query | one of "signin", "sign-in", "api" | No |
Response
200 — The account's result. Cache-Control: no-store, private; creation tokens appear only in this response.
Type: AppManagedKeyList
Errors
| Status | Meaning | Body |
|---|---|---|
| 400 | invalid_kind, invalid_request, invalid_key, invalid_expiry, invalid_name | AppAccountError |
| 401 | signed_out: missing, unsupported, invalid, expired or revoked credential | AppAccountError |
| 409 | no_workspace: kind=api needs the account's first workspace where the account is an owner (normally its personal workspace) | AppAccountError |
| 503 | unavailable: accounts are disabled or the account service failed | AppAccountError |
Example
curl 'https://api.openagents.com/v1/keys' \
-H "Authorization: Bearer $OPENAGENTS_TOKEN"
Create account key
POST /v1/keys · createAccountKey
Create a key and return its secret once. Repeating this request can create another key, even with the same Idempotency-Key header. Do not automatically retry an uncertain result. The sign-in limit is 50 working keys per account. API keys belong to the first workspace where the account is an owner (normally its personal workspace), do not expire, and receive only responses, models:read, usage:read scopes; this is not arbitrary workspace key administration.
Sign-in: a bearer credential in the Authorization header.
appKeyManagementBearer: An account-service-issued live app session (sess_) or sign-in key (oa_sk_). The account service validates it on every request. Cookies and oak_ API keys cannot manage these keys. A sign-in key can create and revoke other sign-in keys for the same account, including itself.
Request body
Content type: application/json
Type: AppManagedKeyCreate
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Sign-in names are trimmed, 1–80 characters, with no control characters. API names are trimmed and truncated to 80 characters; an empty name is refused. |
kind | one of "signin", "sign-in", "api", null | No | Default: |
expires_in_days | integer or null | No | Sign-in keys only. Omitted or null means until revoked. Any non-null expiry with kind=api is refused. |
Response
200 — The account's result. Cache-Control: no-store, private; creation tokens appear only in this response.
Type: AppManagedKeyCreated
Errors
| Status | Meaning | Body |
|---|---|---|
| 400 | invalid_kind, invalid_request, invalid_key, invalid_expiry, invalid_name | AppAccountError |
| 401 | signed_out: missing, unsupported, invalid, expired or revoked credential | AppAccountError |
| 409 | no_workspace: kind=api needs the account's first workspace where the account is an owner (normally its personal workspace) | AppAccountError |
| 503 | unavailable: accounts are disabled or the account service failed | AppAccountError |
Example
curl -X POST 'https://api.openagents.com/v1/keys' \
-H "Authorization: Bearer $OPENAGENTS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "string"
}'
Revoke account key
DELETE /v1/keys/{id} · revokeAccountKey
Revoke a working key of this account. A missing, foreign, expired or already revoked sign-in key returns 404 unknown_key. For kind=api, only a non-revoked key in the first workspace where the account is an owner (normally its personal workspace) is eligible. A repeated successful revoke returns 404, not another success. Revoking the caller's own key ends its access.
Sign-in: a bearer credential in the Authorization header.
appKeyManagementBearer: An account-service-issued live app session (sess_) or sign-in key (oa_sk_). The account service validates it on every request. Cookies and oak_ API keys cannot manage these keys. A sign-in key can create and revoke other sign-in keys for the same account, including itself.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
kind | query | one of "signin", "sign-in", "api" | No | |
id | path | string | Yes | The key ID, not its secret. Sign-in IDs are 64 hexadecimal characters; API IDs are opaque. |
Response
200 — The account's result. Cache-Control: no-store, private; creation tokens appear only in this response.
Type: AppManagedKeyRevoked
| Field | Type | Required | Description |
|---|---|---|---|
kind | one of "signin", "api" | Yes | |
key | object | Yes | |
key.id | string | Yes | |
key.state | always "revoked" | Yes |
Errors
| Status | Meaning | Body |
|---|---|---|
| 400 | invalid_kind, invalid_request, invalid_key, invalid_expiry, invalid_name | AppAccountError |
| 401 | signed_out: missing, unsupported, invalid, expired or revoked credential | AppAccountError |
| 404 | unknown_key | AppAccountError |
| 409 | no_workspace: kind=api needs the account's first workspace where the account is an owner (normally its personal workspace) | AppAccountError |
| 503 | unavailable: accounts are disabled or the account service failed | AppAccountError |
Example
curl -X DELETE 'https://api.openagents.com/v1/keys/{id}' \
-H "Authorization: Bearer $OPENAGENTS_TOKEN"