APIs
Proteja sus APIs como recursos OAuth: defina scopes, controle el acceso machine-to-machine y de usuarios, y fije formato y duración de los tokens.
Una API representa un recurso protegido para el que las aplicaciones obtienen access tokens. Al registrar una API, la plataforma conoce el identificador del recurso (su audience), los scopes (permisos) que expone, qué aplicaciones pueden llamarla y cómo se estructuran y firman los access tokens que se emiten para ella.
Las APIs se gestionan en Integraciones → APIs en la Admin Console.
Qué es una API
Cada API tiene:
- un nombre: una etiqueta para los administradores, y
- un identificador: el valor de audience que aparece en los tokens emitidos para esta API (por ejemplo,
https://api.example.com).
En una API propia también puede indicar contactos, los empleados a los que consultar sobre ella. Son puramente informativos y no reciben ningún derecho.
Hay dos tipos:
- System API: la API de gestión propia de la plataforma. Su nombre, su identificador y sus scopes son fijos y no se pueden editar.
- Custom API: una API que usted registra y gobierna: define sus scopes, quién puede llamarla y su configuración de tokens.
Scopes (permisos)
Un scope es un permiso individual que puede contener un token, por ejemplo read:documents u orders.write.
- La System API expone un catálogo fijo de scopes de gestión (por ejemplo
users.read,users.write,groups.read,roles.write,logs.read). Son los scopes que se conceden a las aplicaciones que llaman a la API de gestión propia de la plataforma. - Una Custom API expone los scopes que usted define. En la pestaña de permisos de la API, añada cada scope con un nombre y una descripción. Algunos scopes reservados de OpenID Connect (como
openid,profile,email,offline_access) no se pueden redefinir.
Algunos scopes de gestión se sitúan deliberadamente junto a su scope base en lugar de estar incluidos en él. El que conviene conocer es users.mfa.read, que cubre los registros de MFA de un usuario (qué segundos factores están registrados y cuándo se utilizó cada uno por última vez). Es obligatorio en todos los endpoints que devuelven un usuario, incluidas las respuestas de las llamadas de creación, actualización, eliminación, desactivación y activación. Un token que solo contiene users.read o users.write recibe el usuario sin la lista de registros, por lo que debe conceder además users.mfa.read cuando una integración la necesite.
Quién puede llamar a una API
Dos políticas independientes controlan el acceso, una para cada tipo de llamante:
Acceso delegado por el usuario
Cuando una aplicación interactiva solicita un token en nombre de un usuario que ha iniciado sesión, la user policy de la API decide si está permitido:
- Allow all: cualquier aplicación interactiva puede solicitar tokens para esta API.
- Require grant: solo las aplicaciones a las que usted haya concedido acceso explícitamente pueden solicitar tokens, y solo para los scopes que les conceda.
- Deny all: ninguna aplicación interactiva puede solicitar tokens.
Acceso machine-to-machine
Cuando una aplicación se autentica como ella misma con el grant client-credentials (sin intervención de ningún usuario), la client policy de la API decide si está permitido:
- Require grant: solo las aplicaciones a las que usted haya concedido acceso explícitamente pueden solicitar tokens, limitados a los scopes concedidos.
- Deny all: ninguna aplicación machine-to-machine puede solicitar tokens.
Conceder acceso a una aplicación
Cuando una política está en require grant, autorice una aplicación desde la pestaña Acceso a la aplicación de la API:
- Elija Añadir aplicación en la sección de acceso delegado por el usuario o en la de cliente (machine-to-machine).
- Seleccione la aplicación.
- Seleccione los scopes que desea conceder, o elija grant all permissions para incluir automáticamente los scopes actuales y futuros.
- Guarde. Los tokens que la plataforma emite para esa aplicación y esta API contienen ahora los scopes concedidos.
Una aplicación machine-to-machine suele ser del tipo de aplicación machine-to-machine; consulte Aplicaciones.

Probar un token de API
En cuanto una API tiene al menos una aplicación machine-to-machine autorizada (con el grant client-credentials), la pestaña Probar de la API le permite probar un token de principio a fin sin escribir código:
- Seleccione una de las aplicaciones machine-to-machine autorizadas.
- La página muestra un ejemplo de solicitud de token listo para ejecutar contra el token endpoint, que utiliza el client ID y el secret de esa aplicación y el identificador de esta API como audience.
- Muestra la respuesta del token y decodifica el access token emitido en su header, su payload y su firma, para que pueda confirmar que la audience y los scopes concedidos son los esperados.
- Muestra un ejemplo de llamada a la API que envía el token como cabecera
Bearer.
Copie los comandos para ejecutarlos en su propio terminal. Si la pestaña Probar le indica que primero debe autorizar una aplicación, conceda acceso a una aplicación machine-to-machine en la pestaña Acceso a la aplicación y vuelva a cargar la página.
Resource indicators y tokens
Cada access token que la plataforma emite para una API lleva el identificador de esa API como audience, de modo que el recurso puede verificar que el token estaba destinado a él. Las aplicaciones eligen para qué API quieren un token mediante el resource indicator, lo que permite que una aplicación tenga tokens separados, limitados a su audience, para varias APIs.
En la pestaña de configuración de la API se controla cómo se estructuran esos tokens:
- Algoritmo de firma: el algoritmo asimétrico (RS256, RS384, RS512 o PS256) con el que se firman los tokens. Elija PS256 para una API a la que llama una aplicación con un perfil de seguridad Financial-grade API: ese perfil firma los tokens propios de la aplicación con PS256 y desaconseja RS256. Esta configuración es independiente del perfil, por lo que también debe cambiarse aquí.
- Access token lifetime: cuánto tiempo es válido un token (de forma predeterminada, un día).
- Implicit access token lifetime: una duración más corta que se aplica a los tokens emitidos mediante flujos implícitos basados en el navegador (de forma predeterminada, dos horas).
¿Una API o varias?
Un access token lleva siempre exactamente una audience. No se emiten tokens con varias audiences: un token emitido para una API no es aceptado por otra (consulte La API como contrato verificable). Si su backend es un conjunto de microservicios, esto plantea una decisión de diseño:
Una API lógica para un dominio de confianza. Registre una única API cuyo identificador represente todo el backend (por ejemplo https://api.example.com) y asigne a cada servicio su propio espacio de nombres de scopes (orders.read, inventory.write, etc.). Cada servicio valida la misma audience y aplica solo sus propios scopes; el cliente tiene un único token para todo el backend, y un servicio nuevo se incorpora añadiendo scopes en lugar de un registro nuevo. Elija esta opción cuando los servicios se desarrollan y operan conjuntamente, normalmente detrás de un gateway. Tenga en cuenta la contrapartida: dentro de la audience compartida, los servicios ya no se aíslan entre sí mediante la comprobación de la audience (cualquiera de ellos acepta un token que se envió a un servicio hermano), sino solo mediante los scopes.
Una API por frontera de confianza. Registre APIs separadas cuando los recursos tengan distintos niveles de confianza o propietarios, o cuando intervengan terceros. Un cliente solicita entonces un token separado por API mediante el resource indicator (consulte Resource indicators y tokens), y un servicio de backend puede intercambiar un token que ya tiene mediante token exchange. A través de la frontera, la comprobación de la audience sigue siendo significativa: un token capturado en una API no vale nada en la otra.
Combinar ambos enfoques es habitual: una API lógica para el núcleo cohesionado y APIs separadas para las partes que necesitan un aislamiento más fuerte.
Hasta dónde reenviar el token de un usuario. Trate el access token del usuario como una credencial, no como contexto de la solicitud. Reenvíelo como máximo un salto, desde el cliente hasta el borde de su API (el gateway o el primer servicio). Los servicios situados más adentro en una cadena de llamadas deberían estar detrás de la audience compartida de la API lógica o recibir un token más restringido emitido mediante token exchange; cada salto adicional que recorre el token original amplía el ámbito en el que un token filtrado puede reutilizarse.
Token exchange
El token endpoint admite OAuth 2.0 Token Exchange (RFC 8693) para que un servicio pueda llamar a una API posterior en nombre de un usuario que ha iniciado sesión sin reenviar el token original: la aplicación intercambia un access token de usuario que ya tiene por un token nuevo y más restringido destinado a otra API.
El grant se limita deliberadamente a la reducción de scopes (downscoping):
- Solo una aplicación web (confidencial) puede utilizarlo, y solo cuando Token exchange está activado entre sus tipos de grant (consulte Aplicaciones).
- El subject token debe ser un access token de usuario aún válido, emitido para la misma aplicación que realiza el intercambio. No se admite intercambiar tokens de otras aplicaciones, tokens sin usuario ni la delegación con un
actor_token. - La solicitud indica exactamente una API de destino mediante
resource. La política de acceso delegado por el usuario de la API de destino se aplica a la aplicación que realiza el intercambio como en cualquier otra solicitud de token. - El token emitido nunca es más amplio que el subject token: sus scopes son la intersección de los scopes solicitados, los scopes del subject token, los scopes de la API de destino y aquello a lo que el usuario tiene derecho.
- El token nuevo sigue vinculado al mismo usuario y a la misma sesión y sigue la configuración de duración de tokens de la API de destino.
Ejemplo de solicitud contra el token endpoint (la aplicación se autentica como de costumbre, por ejemplo con su client secret):
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.readLa respuesta contiene el nuevo access_token junto con expires_in y el scope concedido efectivamente.
Scopes frente a permisos
Definir un scope en una API solo lo hace solicitable; no concede acceso a nadie. Lo que acaba realmente en un token se decide por separado:
- En los tokens machine-to-machine, el token contiene exactamente los scopes que autoriza el client grant de la aplicación (consulte Conceder acceso a una aplicación). Un cliente máquina no tiene usuario ni roles, por lo que asignar un rol a una aplicación machine-to-machine no tiene ningún efecto; sus scopes proceden únicamente del grant.
- En los tokens con usuario (emitidos cuando una aplicación interactiva solicita un token en nombre de un usuario que ha iniciado sesión), el control de acceso basado en roles decide a qué scopes tiene derecho el usuario. Los scopes que acaban en el token son la intersección de lo que solicitó la aplicación y de aquello a lo que el usuario tiene derecho.
Esta es la respuesta habitual a "¿por qué falta sin aviso en mi token el scope que solicité?": el scope se solicitó, pero el llamante no tenía derecho a él, por lo que se descartó en lugar de rechazarse.
Defensa en profundidad: un scope presente en un token es una concesión, no una garantía. Su API debe seguir aplicando sus propias comprobaciones a nivel de objeto (¿es este usuario el propietario de este registro?); un token válido con un scope amplio no sustituye a la autorización sobre el propio recurso.
Control de acceso basado en roles
Nota sobre el plan: El control de acceso basado en roles está disponible a partir del plan Advanced (y en Trial).
Una Custom API puede activar RBAC, lo que permite a la plataforma incluir los roles y permisos de un usuario directamente en los tokens que emite para esa API. En la pestaña de configuración de la API:
- Incluir roles y permisos (RBAC) lo activa para la API.
- Incluir el claim permissions incluye los scopes concedidos al usuario para esta API como claim
permissions. - Incluir el claim roles incluye los nombres de los roles del usuario como claim
roles.
Estos claims solo se añaden a los tokens con usuario. A continuación, la aplicación toma las decisiones de autorización a partir de esos claims. Para definir roles y asignarlos a usuarios y grupos, consulte Roles.
Esas decisiones corresponden al access token. Un claim roles también llega al ID token cuando una aplicación solicita el scope roles, pero ese solo sirve para la presentación; consulte Aplicar en el access token, no en el ID token.
La API como contrato verificable
Una API registrada es, en la práctica, un contrato entre usted y el resource server:
- Su identificador es estable y se convierte en la audience de cada token emitido para ella.
- La plataforma firma cada token con su clave de firma (consulte Claves de firma).
- El resource server valida el token antes de confiar en cualquier scope: comprueba la firma, que el issuer sea esta plataforma y que la audience coincida con su propio identificador, y después lee los scopes.
Si alguna de estas comprobaciones falla, el resource server debe rechazar la solicitud directamente.
Llamar a la API de gestión (inicio rápido machine-to-machine)
Para que un script o un servicio de backend llame a la API de gestión propia de la plataforma:
- Cree una aplicación machine-to-machine; consulte Aplicaciones.
- En la pestaña de acceso a la aplicación de la System API, conceda a esa aplicación los scopes de gestión que necesita (por ejemplo
users.read,groups.write). Conceda solo los scopes que la integración utiliza realmente. - Desde su servicio, solicite un token con el grant client-credentials contra el token endpoint, utilizando el identificador de la System API como audience.
- Llame a los endpoints de gestión bajo
/api/v1/...con el token devuelto en la cabeceraAuthorization: Bearer.
La pestaña Probar de la System API genera exactamente estos dos comandos, rellenados previamente con una aplicación real; cópielos como punto de partida.
Un token deja de funcionar antes de caducar en cuanto la aplicación pierde su acceso a la System API, se rota su client secret o se elimina la aplicación. El servicio recibe entonces HTTP 401 y tiene que solicitar un token nuevo.
Límites de tokens machine-to-machine
A los tokens emitidos mediante el grant client-credentials se aplican dos límites. Ambos se muestran en el resumen de Integraciones → APIs. Los tokens de inicios de sesión interactivos de usuarios nunca se ven afectados por ninguno de ellos.
Solicitudes de tokens por minuto y cliente: el límite de rendimiento. Las solicitudes que lo superan reciben como respuesta HTTP 429 y una cabecera Retry-After; el cliente puede volver a intentarlo una vez transcurrido el tiempo de espera indicado en la cabecera.
| Plan | Solicitudes de tokens por minuto |
|---|---|
| Trial | 30 |
| Free | 60 |
| Essential | 1.200 |
| Advanced | 6.000 |
| Pro | 30.000 |
Tokens al mes, para todo el tenant: un presupuesto de volumen que solo existe en los planes de entrada. Abarca todas las aplicaciones machine-to-machine y todas las APIs en conjunto y se restablece el día 1 de cada mes. Una vez agotado, las siguientes solicitudes client-credentials reciben como respuesta access_denied hasta que comienza el mes siguiente.
| Plan | Tokens al mes |
|---|---|
| Trial / Free | 1.000 |
| Essential y superiores | Ilimitado |
Un cliente que almacena en caché su access token durante toda su duración necesita unos 720 tokens al mes y se mantiene muy por debajo de ambos límites, por lo que normalmente solo alcanza alguno de ellos un cliente que solicita un token nuevo para cada llamada a la API. Almacene el token en caché en el servicio que realiza la llamada y reutilícelo hasta poco antes de que caduque; la duración del token se configura por API en la pestaña de configuración de la API.
Referencia para desarrolladores / de la API
La plataforma incluye documentación interactiva de la API integrada en el producto en /admin/api-docs. Enumera cada endpoint de gestión con sus parámetros y le permite probar llamadas en el navegador, y desde la misma página puede descargar la definición OpenAPI legible por máquina.
La API de gestión abarca la administración de usuarios, grupos, organizaciones, aplicaciones, roles, registros y dispositivos. Utilice /admin/api-docs como referencia autorizada de endpoints en lugar de una lista estática aquí.
Referencia
| Término | Significado |
|---|---|
| Identificador (audience) | El valor que identifica la API; aparece en los tokens emitidos para ella. |
| Scope / permiso | Una capacidad individual que puede contener un token. |
| User policy | Si las aplicaciones interactivas pueden obtener tokens en nombre de un usuario. |
| Client policy | Si las aplicaciones pueden obtener tokens para sí mismas (machine-to-machine). |
| Grant | Una autorización explícita de una aplicación para llamar a esta API con scopes concretos. |
| RBAC | La inclusión de los roles y permisos de un usuario en los tokens de la API. |
| Token exchange | El intercambio de un access token de usuario por un token más restringido destinado a otra API (RFC 8693). |
Solución de problemas
- La solicitud de token se rechaza con un scope no válido. Una aplicación solo puede solicitar los scopes que se le han concedido en la API. Añada el scope al grant de la aplicación para esta API y, a continuación, solicite un token nuevo.
- Las llamadas devuelven un error de scope insuficiente aunque se emitió un token. Una solicitud solo tiene éxito si el token contiene realmente el scope que exige el endpoint. Decodifique el token y confirme que los scopes concedidos lo incluyen; los scopes que no se concedieron a la aplicación se descartan del token sin aviso.
- El token tiene una audience incorrecta. El token debe solicitarse para el identificador (audience) de esta API. Un token emitido para otra API, o sin audience, no se acepta aquí.
- La prueba de token no devuelve nada o devuelve un error. La prueba emite un token para la aplicación y los scopes seleccionados. Asegúrese de que la aplicación tiene un grant activo en esta API y de que hay al menos un scope seleccionado.
- Se rechaza un token exchange. El subject token debe ser un access token con usuario aún válido, emitido para la misma aplicación que realiza el intercambio; la aplicación debe tener activado el grant token-exchange, y la solicitud debe indicar exactamente una API de destino mediante
resource. Los tokens machine-to-machine (sin usuario) no se pueden intercambiar.
Consulte también el glosario.
Aprovisionamiento de aplicaciones
Cree, actualice y desactive cuentas en aplicaciones posteriores automáticamente mediante SCIM saliente, con asignaciones de atributos y grupos.
Roles
Agrupe permisos de API en roles y asígnelos a usuarios y grupos, para que las aplicaciones autoricen en función del rol.