Hacer peticiones con una clave

Tu servidor envía la clave en cada petición y llama a las mismas rutas que usa la aplicación, en https://os.utilia.ai/api. Cada petición se comprueba de nuevo: si revocas la clave o cambias los permisos de su persona responsable, la petición siguiente ya lo nota. Si todavía no tienes la clave, empieza por Claves de API de la organización.

Dónde va la clave

Envía la clave en la cabecera Authorization, con Bearer delante, en cada petición:

Authorization: Bearer utk_…

No vale en la dirección ni en la cabecera X-Api-Key: ahí no autentica. Y solo desde un servidor: si la petición lleva las cabeceras Origin o Sec-Fetch-Site, que pone un navegador, UTILIA OS la rechaza.

Comprobar que funciona

Para saber que la clave está bien puesta, pregúntale quién es:

curl 'https://os.utilia.ai/api/v2/organization-api-keys/current' \
  -H "Authorization: Bearer $UTILIA_API_KEY"

Si la clave funciona, recibes un 200 como este:

{
  "id": "cm2k8x0ab0001qz7f3d4e5f6g",
  "name": "Cuadro de mando de ventas",
  "keyPrefix": "utk_Ab12Cd34",
  "responsibleUser": {
    "id": "cm1z9y8xw0000ab12cd34ef56",
    "firstName": "María",
    "lastName": "García",
    "email": "maria@tuempresa.com"
  },
  "permissionMode": "RESTRICTED",
  "moduleAccess": ["crm:read", "finance:read"],
  "effectivePermissions": [
    { "moduleKey": "crm", "label": "CRM", "read": true, "write": false },
    { "moduleKey": "finance", "label": "Finanzas", "read": true, "write": false }
  ],
  "expiresAt": null,
  "rateLimitPerHour": 1000,
  "rateLimitRemaining": 998,
  "rateLimitResetAt": "2026-10-21T11:00:00.000Z",
  "usedPreviousKey": false,
  "previousKeyExpiresAt": null
}

permissionMode'ALL' | 'READ_ONLY' | 'RESTRICTED'obligatorio

Todos los permisos, Solo lectura o Restringido.

moduleAccessstring[]obligatorio

Solo con RESTRICTED: un acceso por módulo, 'modulo:read' o 'modulo:write'. Vacío en los otros dos modos.

effectivePermissionsobject[]obligatorio

Lo que la clave puede hacer hoy en cada módulo, después de cruzar los permisos de la persona, lo marcado en la clave y el plan.

expiresAtstring | nullobligatorio

Fecha de caducidad en ISO 8601, o null si no caduca.

rateLimitRemainingnumber | nullobligatorio

Peticiones que le quedan a la clave en la hora en curso; null si no se puede saber en ese momento.

rateLimitResetAtstringobligatorio

Cuándo se renueva el cupo: al empezar la hora siguiente.

usedPreviousKeybooleanobligatorio

true si la petición entró con la clave anterior de una renovación que todavía está en transición.

previousKeyExpiresAtstring | nullobligatorio

Hasta cuándo vale la clave anterior de una renovación en transición, o null si no hay ninguna.

Esta ruta cuenta como una petición más de tu cupo. Si expiresAt trae una fecha, apúntala: cómo te avisa UTILIA OS antes de que llegue está en Caducidad, renovación y revocación.

Llamar a las rutas de la aplicación

Con la clave llamas a las mismas rutas que usa la aplicación. Por ejemplo, con «CRM: leer» lees tus clientes y con «CRM: escribir» das de alta uno nuevo:

curl 'https://os.utilia.ai/api/crm/clients?limit=20' \
  -H "Authorization: Bearer $UTILIA_API_KEY"
 
curl -X POST 'https://os.utilia.ai/api/crm/clients' \
  -H "Authorization: Bearer $UTILIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Talleres Rivera"}'

El cliente nuevo queda creado por la persona responsable de la clave, y su organización sale siempre de la clave, nunca del cuerpo de la petición.

Ten en cuenta dos cosas al elegir rutas:

• Son las rutas de la aplicación y cambian con ella. No tienen la versión ni el contrato estable de la API externa (/api/external/v1). Para saber qué ruta usa una pantalla, ábrela con las herramientas de desarrollo de tu navegador y mira la pestaña Red.
• Los SDK oficiales de JavaScript y Python son clientes de la API externa y no sirven con esta clave. Usa cualquier cliente HTTP, como en los ejemplos.

Qué se comprueba en cada petición

Cada petición pasa unos controles en orden, y el primero que falla la corta con su código. Los cinco primeros miran la clave:

Si la clave pasa, los tres últimos miran la ruta que llamas y a la persona responsable, igual que harían con ella en la aplicación:

Nada se guarda en memoria entre peticiones: revocar una clave, dar de baja a su responsable o quitarle un permiso surte efecto en la petición siguiente. Qué permite cada modo y qué queda fuera de cualquier clave está en Permisos de una clave.

Errores de una petición

Todos llegan con la forma común de los errores: decide con errorCode y guarda requestId. Los de permisos añaden permissions, la lista de permisos que faltan.

De todos ellos, solo merece la pena reintentar API_KEY_UNAVAILABLE y RATE_LIMIT_EXCEEDED, con espera. Los demás no cambian por repetir la petición.

Siguiente paso

• Errores y reintentosLa forma de un error, X-Request-Id y cuándo merece la pena reintentar.