Autenticación

API keys de OlivIA (Bearer oc_sk_) y roles de acceso

La API de OlivIA se autentica con una API key personal enviada como bearer token en cada petición:

Authorization: Bearer oc_sk_...

curl "https://{your-prod-endpoint}/v1/protocols" \
  -H "Authorization: Bearer oc_sk_xxxxxxxxxxxxxxxxxxxxxxxx"

​

Cómo obtener una key

Las API keys se emiten desde la plataforma por un administrador de tu organización (no hay auto-registro por API). Cada key queda ligada a un usuario y a una organización, y hereda el rol de ese usuario: la tenencia (org_id) y los permisos se derivan de la key, así que no necesitas enviar ningún identificador de organización.

La key se muestra una sola vez en el momento de crearla. Guárdala en un gestor de secretos; OlivIA solo almacena un hash y no puede recuperarla. Si se compromete, revócala y emite una nueva.

​

Roles y permisos

Cada endpoint exige un rol mínimo. El rol efectivo de la key es el del usuario propietario.

Operación	Roles permitidos
Lecturas (protocolos, inscripciones, runs, llamadas)	admin, coordinator, medic
Inscribir paciente / crear run	admin, coordinator
Archivar (eliminar) protocolo	admin, integrator

Si una key no tiene el rol necesario, la API responde 403.

​

Qué datos ve cada rol

Además del rol, cada lectura se limita a los pacientes que el usuario de la key necesita ver:

Rol	Ve
admin	Toda la organización.
coordinator	Las inscripciones de los protocolos de sus grupos (y de los protocolos sin grupos). Solo inscribe y asigna responsable en esos protocolos, y puede llevarlas él mismo.
medic (personal sanitario)	Los pacientes con alguna inscripción asignada a él, con su historia completa. Solo actúa sobre sus inscripciones.

Leer un recurso concreto fuera de ese alcance responde 404, igual que si no existiera. Los listados no fallan: GET /v1/protocols responde 200 con solo las entradas que la key puede ver, así que una lista más corta —o vacía— es la respuesta esperada, no un error.

​

Buenas prácticas

• Usa una key distinta por integración o entorno para poder revocarla de forma aislada.
• No incrustes la key en clientes front-end ni en repositorios.
• Rota las keys periódicamente.