Autenticación y scopes
Claves sk_live_, los siete scopes y qué comprobar antes de escribir código.
Toda ruta bajo /v1 va autenticada con una cabecera:
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxLas claves empiezan por sk_live_, se crean en
app.callsist.com/keys y se muestran una sola vez.
No hay claves de prueba. Existieron sk_test_ y se retiraron: no se regalan resultados,
así que cada llamada consume saldo real. No es caro —el recorrido completo sobre un audio
corto son unos 0,011 €— pero conviene saberlo antes de montar un bucle.
Scopes
Cada clave lleva una lista de permisos. Una petición sin el scope necesario devuelve
403 missing_scope.
| Scope | Da acceso a |
|---|---|
transcripts:write | POST/DELETE /v1/transcripts, gestión de webhooks |
transcripts:read | GET /v1/transcripts, GET /v1/transcripts/{id}, subtítulos |
files:write | POST/GET/DELETE /v1/files |
llm:invoke | POST /v1/chat/completions |
embeddings:invoke | POST /v1/embeddings |
usage:read | GET /v1/balance |
understand:write | Reservado. Hoy no lo exige ningún endpoint |
GET /v1/me
Lo primero que hay que llamar al integrar. No consume saldo.
{
"organization": { "id": "aef52135-…", "slug": "acme-bpo" },
"key": {
"id": "e03e9a93-…",
"environment": "live",
"scopes": ["transcripts:write", "transcripts:read", "files:write", "llm:invoke", "embeddings:invoke", "usage:read"]
},
"default_retention": "30d"
}GET /v1/balance
Requiere usage:read. Conviene consultarlo antes de encolar un lote grande: sin
saldo, cada POST /v1/transcripts devuelve
402 sin procesar nada.
{ "balance_eur": 109.9, "currency": "EUR", "spend_cap_eur": null, "environment": "live" }Lista blanca de IPs
Una clave puede restringirse a un conjunto de IPs. Si la petición llega desde fuera, la
respuesta no es el código que parecería: es
403 missing_scope con param: "ip_allowlist". El
código ip_not_allowed está publicado y no se
emite nunca.
Es el error más desconcertante de la API y por eso está dicho aquí y no solo en la tabla: si una clave que funcionaba deja de funcionar desde una máquina nueva, mira la lista blanca antes que los scopes.
Un detalle de operación
Una clave revocada sigue funcionando hasta 30 segundos, que es lo que dura la caché de autenticación. Si revocas una clave por una filtración, cuenta medio minuto antes de dar por cerrada la puerta.