Ámbitos de las claves
Un ámbito nombra una parte de la API a la que una clave puede llamar. Cada endpoint de la
referencia de la API declara el único ámbito que necesita. Una solicitud con una clave que no lo tiene
se rechaza con 403 y el código api_keys.scope, antes de leer o cambiar nada.
Los ámbitos indican qué operaciones puede llamar una clave. El rol, el perfil de datos y las colecciones de la clave
siguen decidiendo qué objetos ven esas operaciones: una clave con cards:write y el rol viewer no puede cambiar
tarjetas, y una clave limitada a una colección no ve las demás.
Ámbitos
| Ámbito | Permite |
|---|---|
cards:read | Leer tarjetas, colecciones y carpetas. |
cards:write | Crear, cambiar y eliminar tarjetas, colecciones y carpetas. |
search | Buscar en la base de conocimiento (POST /v1/search). |
ask | Preguntar al asistente (POST /v1/ask, POST /v1/chat). |
import:write | Escribir en las fuentes personalizadas de la organización: sincronizaciones, lotes y eliminaciones, y leer su estado. Para crear una fuente y sus claves hace falta admin. |
webhooks:manage | Gestionar los webhooks y leer el feed de eventos (GET /v1/webhook-events). Las dos cosas requieren además el rol admin. |
users:read | Leer usuarios y grupos. |
users:write | Cambiar usuarios y grupos. |
analytics:read | Leer las analíticas. |
audit:read | Leer el registro de auditoría. |
finance:read | Leer informes financieros, facturas y pagos. |
catalog:read | Leer el catálogo de servicios. |
files:read | Leer archivos generados, como las respuestas exportadas. |
files:write | Cambiar y eliminar archivos generados. |
permissions:manage | Conceder y revocar permisos sobre objetos. |
admin | La configuración de la organización y sus claves de API. Una clave con admin también tiene todos los demás ámbitos. |
Por su significado, la búsqueda y las preguntas son lecturas: una clave que solo puede leer también puede buscar y preguntar.
Elegir los ámbitos
Conceda los ámbitos que usa una integración y nada más:
| Integración | Ámbitos |
|---|---|
| Bot de preguntas y respuestas en una herramienta de chat | search, ask |
| Importación desde su sistema de documentos | cards:write (API de tarjetas) o import:write (fuente personalizada) |
| Exportación a un almacén de datos | cards:read, users:read y webhooks:manage para el feed de eventos |
| Alta de usuarios desde su sistema de RR. HH. | users:write |
Pase la lista al crear la clave:
curl -X POST https://api.sursa.com/v1/api-keys \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'Ámbitos anteriores
Las claves creadas antes de que se dividieran los ámbitos siguen funcionando. Sus ámbitos read, write y admin
equivalen a estos conjuntos:
| Ámbito anterior | Significa |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | todo lo de read, más cards:write, files:write, users:write, permissions:manage |
admin | todos los ámbitos |
Una clave creada sin ámbitos explícitos los recibe de su rol: admin recibe admin; editor y verifier reciben
write; viewer recibe read.
Ver los ámbitos de una clave
GET /v1/me devuelve los ámbitos de la clave que hace la solicitud, sean cuales sean sus
ámbitos. En una clave creada sin ámbitos explícitos, son los ámbitos anteriores de su rol, como read y write; la
tabla de arriba muestra a qué equivalen. Cuando una operación falla con api_keys.scope, error.message indica el
ámbito que faltaba.