Autorización

Autorización

Una vez que una API key ya fue autenticada, la autorización determina a qué endpoints y operaciones puede acceder.

En otras palabras:

• la autenticación confirma quién está llamando
• la autorización define qué puede hacer esa integración

Si necesitas repasar creación, uso y renovación de API keys, vuelve a la guía de autenticación.

Modelo de autorización

Después de autenticar el request, Soyio evalúa acceso en capas:

1. confirma que la API key esté activa
2. confirma que tu cuenta tenga habilitado el módulo al que pertenece el endpoint
3. revisa los permisos requeridos por el endpoint
4. aplica restricciones del recurso, como existencia o pertenencia
5. aplica reglas adicionales, por ejemplo feature flags o reglas de negocio

La operación solo se ejecuta cuando todas las capas pasan.

Módulos habilitados

Cada cuenta tiene un conjunto de módulos contratados (Consentimiento, Gestión de Derechos, Validación de Identidad, Workflows, Formulario de Consentimiento y REDEC). Antes de revisar los permisos, Soyio verifica que tu cuenta tenga habilitado el módulo al que pertenece el endpoint.

Si llamas a una operación de un módulo que tu cuenta no tiene habilitado, la respuesta es un 403 que indica el módulo faltante y el correo de contacto para activarlo. Como este chequeo ocurre antes que el de permisos, recibirás el 403 aunque tu API key tenga los permisos correspondientes. Revisa el formato del error en la guía de errores.

En sandbox todos los módulos están disponibles para que pruebes tu integración; en producción solo responden los módulos que tu cuenta tiene contratados.

Cómo definir el acceso de una API key

Puedes gestionar permisos desde el dashboard de Soyio o vía API al crear y actualizar API keys.

Hoy el acceso de una API key se define con el campo permissions.

• Crear API key: POST /api_keys
• Actualizar API key: PATCH /api_keys/{id}

Ejemplo válido:

{
  "api_key": {
    "label": "Integration Worker",
    "permissions": [
      "consent_actions.api.read",
      "api_keys.api.manage"
    ]
  }
}

Ejemplo inválido:

{
  "api_key": {
    "permissions": ["*.api.manage"]
  }
}

*.api.manage es solo una forma de explicar el patrón.

No es un permiso literal. Debes enviar strings exactos, por ejemplo consent.api.manage, branches.api.write o api_keys.api.read.

precaución

El campo scopes es un modelo legacy. Úsalo solo si tu integración ya depende de él; para integraciones nuevas usa permissions.

• scopes y permissions son mutuamente excluyentes: una API key solo puede tener uno de los dos.
• Cada patrón de scopes hace match exacto de path, salvo que termine en /*, en cuyo caso también permite cualquier ruta anidada bajo ese prefijo.
• Si el path solicitado no está cubierto por ninguno de los scopes de la key, la API responde 401 con type: authentication_error.
• Si tienes una API key con scopes, considera migrarla a permissions la próxima vez que la actualices. Para hacerlo, envía el label actual, vacía scopes y agrega los permisos nuevos en la misma solicitud.

Cómo se estructuran los permisos

Los permisos actuales siguen el nombre del recurso en la referencia de API. Algunos ejemplos reales hoy son:

• api.read
• api.write
• api.manage
• branches.api.read
• branches.api.write
• products.api.manage
• consent_actions.api.read
• consent_commits.api.write
• data_subject_requests.api.config
• disclosure_requests.api.read
• api_keys.api.manage

Tipos de permisos

1. Permisos globales de la API

• api.read: habilita todas las lecturas
• api.write: habilita todas las escrituras
• api.manage: habilita toda la API

important

api.write no implica lecturas.

Si una integracion necesita leer y escribir, asigna api.manage o combina api.read con los permisos de escritura que correspondan.

2. Permisos por recurso

La mayoría de recursos siguen el patrón <resource>.api.<ability>.

Ejemplos:

• branches.api.read
• branches.api.write
• reports.api.read
• reports.api.write
• government_check_requests.api.manage

Cuando un recurso expone manage, ese permiso actúa como shortcut del recurso completo.

Por ejemplo:

• products.api.manage incluye products.api.read y products.api.write
• data_subject_requests.api.manage incluye data_subject_requests.api.read, data_subject_requests.api.write y data_subject_requests.api.config

3. Permisos agrupadores por familia

Algunas familias también tienen permisos agrupadores para reunir recursos relacionados:

• consent.api.read, consent.api.write, consent.api.config, consent.api.manage
• disclosure.api.read, disclosure.api.write, disclosure.api.config, disclosure.api.manage

Estos permisos agrupadores no reemplazan los permisos de recurso en la referencia, pero pueden aparecer como alternativa válida en x-permissions para endpoints de su familia.

Ejemplo de recursos que caen bajo consent.api.manage:

• consent_templates.api.*
• consent_actions.api.*
• consent_commits.api.*
• consent_revocations.api.*

Ejemplo de recursos que caen bajo disclosure.api.manage:

• disclosure_templates.api.*
• disclosure_requests.api.*

Reglas rápidas de lectura

Toma estas reglas como referencia al diseñar permisos:

• *.api.read = solo lectura del recurso
• *.api.write = solo escritura del recurso
• *.api.config = configuración del recurso
• *.api.manage = acceso completo al recurso o familia

No asumas que write incluye read.

Si quieres ambas capacidades, debes asignarlas explícitamente o usar manage.

Cómo identificar qué acceso necesita un endpoint

En la referencia de API, cada endpoint muestra una sección expandable de Permisos requeridos.

Dentro de esa sección puedes ver dos listas:

• Dashboard: permisos válidos para sesiones del dashboard
• API Keys: permisos válidos para API keys

Piensa cada lista como un *_any_of: basta con tener uno de los permisos listados.

Ejemplo:

Si el endpoint muestra en API Keys:

• consent_actions.api.read
• consent_actions.api.manage
• consent.api.manage

Lectura rápida:

Permisos de la API key	Accede al endpoint
consent_actions.api.read	Si
consent_actions.api.manage	Si
consent.api.manage	Si
data_subject_requests.api.manage	No
ninguno de los anteriores	No

Regla práctica:

• si ves un permiso de recurso, es la opción más acotada
• si ves *.api.manage, ese shortcut también sirve para ese recurso o familia
• si no aparece en la lista del endpoint, no asumas que otorga acceso

Cómo diseñar permisos para una integración

Usa el principio de mínimo privilegio:

1. lista los endpoints que usa tu servicio
2. revisa los permisos del endpoint en la referencia
3. asigna el permiso más acotado posible
4. usa <resource>.api.manage o un permiso agrupador solo si realmente necesitas amplitud operativa
5. revisa permisos cada vez que agregues endpoints nuevos a la integración

Qué revisar si algo falla

Código	Qué suele significar
401 Unauthorized	token ausente, inválido, revocado, no autenticable, o (si la key usa scopes legacy) ningún scope cubre el path solicitado
403 Forbidden	token válido, pero bloqueado por una regla adicional
404 Not Found	recurso inexistente o endpoint que oculta acceso no autorizado

Checklist rápido:

1. confirma que usas Authorization: Bearer <secret_jwt>
2. confirma que la API key sigue activa
3. revisa api_any_of en la referencia del endpoint
4. verifica que tu key tenga uno de esos permisos exactos
5. revisa si el endpoint tiene reglas extra o si el recurso realmente existe

Buenas prácticas operativas

• usa una API key por servicio
• evita compartir una misma key entre sistemas distintos
• revisa permisos cuando cambie el alcance de la integracion
• monitorea uso de keys y revoca las que ya no se usan