Create an API key

Settings module

POST/api-keysapiKeys.create

Creates an API key with scopes and an expiry, optionally for a service account, through `app.create_api_key`. The full secret is returned once; only its hash is stored. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.

Requires the capability org.api_keys.manage.
OAuth scopes: org.
Send an Idempotency-Key header. A replay with the same key returns the original response.
Error statuses: 400, 401, 409, 422, 429. Errors are RFC 9457 problem details.

Request body: ApiKeyCreate

apiKeys.create: ApiKeyCreate
Field	Type	Required	Description
name	string	Yes	Key name.Constraints: length 1 to 300
service_account_id	string (uuid) \| null	No	Identifier of the service account.
scopes	array of string	Yes	Capability groups the key may use.
expires_at	string (date-time)	Yes	Expiry.

{
  "name": "Accounting Sync",
  "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "scopes": [
    "finance"
  ],
  "expires_at": "2026-10-08T14:30:00Z"
}

Response 201: ApiKeySecret

apiKeys.create: ApiKeySecret
Field	Type	Required	Description
api_key_id	string (uuid)	Yes	Identifier of the API key.
secret	string	Yes	The full key. Shown once; only its hash is stored.Constraints: length 1 to any

{
  "api_key_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "secret": "xos_live_7Hq2wQ1nC8vL0pR4tY6u"
}

Code samples

curl -X POST "$XOS_BASE_URL/api-keys" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Accounting Sync","service_account_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","scopes":["finance"],"expires_at":"2026-10-08T14:30:00Z"}'

const { data } = await xos.apiKeys.create({
    "name": "Accounting Sync",
    "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "scopes": [
      "finance"
    ],
    "expires_at": "2026-10-08T14:30:00Z"
  });

response = xos.api_keys.create({"name": "Accounting Sync", "service_account_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "scopes": ["finance"], "expires_at": "2026-10-08T14:30:00Z"})

xos api-keys create --data '{"name":"Accounting Sync","service_account_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","scopes":["finance"],"expires_at":"2026-10-08T14:30:00Z"}'