API keys
Una API key es ccsio_ seguida de 32 letras y dígitos. Pertenece a una organización en una región y actúa con los permisos de la persona o la cuenta a la que pertenece:
| Tipo | Actúa como | Úsala para |
|---|---|---|
| API key personal | Tú: tus roles y permisos en la organización. | Tus propios scripts, notebooks y agentes de código. |
| API key de cuenta de servicio | Una cuenta de servicio, con el rol que le asigna un administrador. | Aplicaciones, servidores y pipelines de CI. |
Crea ambos tipos en la consola, en Identity → API keys. La API key completa se muestra una sola vez, al crearla; después la consola solo muestra su prefijo.
Envía la API key
Envía la API key en el header Authorization como bearer token. Es lo que hacen los clientes de OpenAI con api_key:
curl "https://api.latam.ccsio.ai/v1/models" \
-H "Authorization: Bearer $CCSIO_API_KEY"O envíala en el header x-api-key, si tu herramienta no puede enviar un bearer token:
curl "https://api.latam.ccsio.ai/v1/models" \
-H "x-api-key: $CCSIO_API_KEY"Actuar en nombre de un equipo
Los administradores pueden restringir los modelos a ciertos equipos. Cuando el propietario de una API key pertenece a más de un equipo, indica en X-Team-Id el equipo en cuyo nombre actúa la llamada: los modelos que puedes llamar, los límites y el uso siguen entonces a ese equipo. Sin ese header, a quien tiene roles en varios equipos se le rechaza la solicitud con 403 policy-denied.
curl "$CCSIO_BASE_URL/chat/completions" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "X-Team-Id: devops" \
-H "Content-Type: application/json" \
-d '{"model": "qwen3.8-flash-next", "messages": [{"role": "user", "content": "Hi"}]}'Cuando se rechaza una API key
| Estado | Código | Significado |
|---|---|---|
| 401 | invalid-request | No hay ninguna credencial, o llegaron los dos headers a la vez. |
| 401 | api-key-invalid | El valor no es una API key de la plataforma: verifica que empiece con ccsio_ y que esté completa. |
| 401 | api-key-unknown | La API key no existe en esta región. Las API keys solo funcionan en la región donde se crearon. |
| 401 | api-key-revoked, api-key-expired | La API key fue revocada o venció. Crea una nueva. |
| 402 | payment-required | La organización no tiene una suscripción activa. |
| 403 | policy-denied | Ningún rol del propietario de la API key tiene el permiso, o el equipo es ambiguo: envía X-Team-Id. |
| 403 | team-not-selectable | X-Team-Id nombra un equipo en cuyo nombre el propietario de la API key no puede actuar. |
Todo rechazo tiene la misma estructura, con un code estable en el que puedes basar tu lógica:
{
"error": {
"code": "api-key-revoked",
"category": "client",
"message": "the API key has been revoked",
"request_id": "01K7YQ4D8M2P6S9V3X5Z7B1C4F"
}
}Administra las API keys por API
La automatización puede crear cuentas de servicio y sus API keys mediante la API de administración, en el host de tu consola. La API key que la llama necesita los permisos members.manage y api-keys.manage.
# The management APIs answer on your console's host.
export CCSIO_CONSOLE_URL="https://console.latam.ccsio.ai"
# 1. A service account for the application (permission members.manage).
curl "$CCSIO_CONSOLE_URL/identity/v1/service-accounts" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"org_id": "acme", "display_name": "billing-app", "role": "user"}'
# → {"principal_ref": "svc/01K7YP2C9W4X5E8H3J6M0N1Q2R", "display_name": "billing-app", "kind": "service_account"}
# 2. A key for it (permission api-keys.manage). The answer carries the raw key once, in "raw": store it now.
curl "$CCSIO_CONSOLE_URL/identity/v1/api-keys" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"org_id": "acme",
"name": "billing-app production",
"principal_ref": "svc/01K7YP2C9W4X5E8H3J6M0N1Q2R",
"expires_at": "2027-01-31T00:00:00Z"
}'
# 3. Revoke it when it is no longer needed, or if it leaked.
curl -X POST "$CCSIO_CONSOLE_URL/identity/v1/api-keys/01K7YQ4D8M2P6S9V3X5Z7B1C4F/revoke" \
-H "Authorization: Bearer $CCSIO_API_KEY"Buenas prácticas
- Usa una API key por aplicación y por entorno, para poder revocar una sin detener las demás.
- Ponles una fecha de vencimiento a las API keys de las cuentas de servicio y rótalas antes de que venzan.
- Lee las API keys desde el entorno o desde un almacén de secretos, nunca desde el código ni desde los logs.
- Revoca de inmediato una API key que pudo haberse filtrado: Identity → API keys.