Autenticación

Hay dos credenciales y nunca se mezclan: una vive en tu servidor y lo puede todo, la otra vive en el navegador del titular y sólo puede abrir su propia sesión.

API key

Identifica al integrador. Va en la cabecera authorization como bearer token y autentica todo el plano servidor a servidor: runs, sesiones, catálogo y webhooks.

authorization: Bearer sk_live_tu_api_key

Prefijo	Ambiente	Qué hace
`sk_live_…`	producción	Ejecuta contra los portales reales y factura.
`sk_test_…`	sandbox	Devuelve datos de prueba, no toca ningún portal y no factura.

La API key es secreta y sólo se muestra una vez, al crearla. No la pongas en el navegador, en una app móvil ni en un repositorio: cualquiera que la tenga puede ejecutar runs a tu nombre y a tu costo. Si se expone, rótala.

Token de sesión

Lo emite POST /v1/sessions y lo consume el widget desde el navegador del titular. Con el mismo formato de cabecera:

authorization: Bearer pk_sess_…

Es deliberadamente débil, y esa es su virtud:

Sólo abre su propia sesión: no lista runs, no crea sesiones, no ve otras.
Caduca con la sesión.
Sirve para exactamente dos endpoints: GET /v1/connect/context y POST /v1/connect/credentials.

Por eso puede viajar en una URL y vivir en el navegador sin que eso comprometa nada: lo peor que puede hacer quien lo intercepte es mirar qué se está pidiendo.

Qué credencial usa cada endpoint

Plano	Credencial	Endpoints
Integrador	`sk_live_…` / `sk_test_…`	`/v1/runs`, `/v1/sessions`, `/v1/catalog`, `/v1/webhook_endpoints`
Titular (widget)	`pk_sess_…`	`/v1/connect/*`

Errores de autenticación

HTTP	`code`	Qué pasó
`401`	`authentication_error`	Falta la cabecera, o la key no existe o fue revocada.
`403`	`permission_denied`	La credencial es válida pero no alcanza para ese endpoint — típicamente un token de sesión fuera de `/v1/connect`.