Create an API key

Módulo Settings

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`.

Requiere la capacidad org.api_keys.manage.
Alcances de OAuth: org.
Envía el encabezado Idempotency-Key. Una repetición con la misma clave devuelve la respuesta original.
Estados de error: 400, 401, 409, 422, 429. Los errores son detalles de problema RFC 9457.

Cuerpo de la solicitud: ApiKeyCreate

apiKeys.create: ApiKeyCreate
Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Key name.Restricciones: length 1 to 300
service_account_id	string (uuid) \| null	No	Identifier of the service account.
scopes	array of string	Sí	Capability groups the key may use.
expires_at	string (date-time)	Sí	Expiry.

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

Respuesta 201: ApiKeySecret

apiKeys.create: ApiKeySecret
Campo	Tipo	Obligatorio	Descripción
api_key_id	string (uuid)	Sí	Identifier of the API key.
secret	string	Sí	The full key. Shown once; only its hash is stored.Restricciones: length 1 to any

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

Ejemplos de código

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"}'