Autenticación
Todas las llamadas van con Authorization: Bearer <key>. Lo que
cambia entre credenciales no es el formato sino dónde pueden estar sin ser un
problema.
Tres credenciales
belfort_{env}_sk_…secreta |
La normal. Concede lo que digan sus scopes. Nunca sale de tu servidor: en un bundle de frontend, en una app móvil o en un repositorio, es una filtración, no una configuración. |
belfort_{env}_pk_…publicable |
Diseñada para viajar al navegador. No concede nada por sí sola: solo abre sesiones embebidas contra los orígenes que autorizaste, y con un flujo ya publicado. Si se filtra, lo peor que alguien puede hacer es abrir sesiones desde tu propio dominio. |
ctok_…efímero |
Un client-token: un solo uso, 15 minutos de vida y limitado a los campos concretos que declaraste. Es la forma de que un navegador vea un dato sin que tu clave secreta se acerque a él. |
Scopes
Cada key lleva la lista de lo que puede hacer, y cada operación declara el scope que exige — lo
verás en su ficha, en la referencia. Pedir menos de lo necesario da
INSUFFICIENT_SCOPE, con el scope que faltaba
dentro del error para que no tengas que adivinarlo.
Se aceptan comodines por recurso (persons:*) y el total (*), pero
concede el más angosto que funcione. El que más conviene mirar dos veces es
persons:read_pii: es el único que permite ver datos personales en claro, y cada uso
queda en bitácora.
| Scope | Operaciones | Ejemplos |
|---|---|---|
aml:read |
1 | GET /v1/screening-hits |
aml:write |
2 | POST /v1/monitoring/portfolios/{portfolio_id}/run · POST /v1/screenings |
compliance:read |
6 | GET /v1/audit-logs · GET /v1/audit-logs/verify… |
compliance:write |
1 | POST /v1/compliance/breach-notifications |
embedded:create_session |
1 | POST /v1/embedded/sessions/browser |
kyb:read |
3 | GET /v1/companies · GET /v1/companies/{company_id}… |
kyb:write |
5 | POST /v1/companies · POST /v1/companies/{company_id}/documents… |
persons:read |
15 | GET /v1/persons · GET /v1/persons/export-bulk/{job_id}… |
persons:read_pii |
9 | POST /v1/media-links · POST /v1/persons/batch-decrypt… |
persons:redact |
1 | POST /v1/persons/{person_id}/forget |
persons:write |
13 | POST /v1/persons · POST /v1/persons/import… |
review:read |
4 | GET /v1/review/cases/{case_id} · GET /v1/review/media/{media_id}… |
review:write |
5 | POST /v1/review/cases/{case_id}/claim · POST /v1/review/cases/{case_id}/notes… |
verification:read |
6 | GET /v1/verification-sessions · GET /v1/verification-sessions/{session_id}… |
verification:write |
6 | POST /v1/embedded/sessions · POST /v1/embedded/sessions/{session_id}/verify… |
webhook:read |
8 | GET /v1/developer/webhooks · GET /v1/developer/webhooks/deliveries… |
webhook:write |
5 | POST /v1/developer/webhooks · POST /v1/developer/webhooks/deliveries/{delivery_id}/retry… |
El entorno va en la key
No hay un parámetro mode ni una cabecera de entorno: la key decide.
Una belfort_test_sk_ solo ve datos de prueba y una belfort_live_sk_ solo
ve los reales. No es una convención de nombres — el aislamiento está en las consultas, así que no
existe la llamada que cruce de un lado al otro por error. Ver entornos.
Qué hacer si una key se filtra
Revócala desde el panel. La revocación es inmediata y no tiene periodo de gracia: una key revocada deja de valer en la siguiente petición. Crea la nueva antes de revocar la vieja si necesitas continuidad.