API · EMPEZAR

Claves y permisos

Cada llamada lleva una clave de servicio en la cabecera. La clave dice qué espacios alcanzas y si puedes escribir; Bentho lo recalcula en cada petición.

La clave

CABECERA

Authorization: Bearer bth_<id>.<secreto>

bth_, luego un id de 16 caracteres hexadecimales, un punto y un secreto de 43 caracteres (base64url).
El secreto se ve una sola vez, al crearla. Bentho solo guarda su huella y la compara en tiempo constante.
No caduca: vale hasta que la revocas o deja de cumplirse lo que la sostiene (abajo).

Crear una clave

Lo normal es crearla en la consola, en el módulo API de tu espacio. Al menos uno de sus espacios tiene que tener contratado el módulo Bentho API.

CAMPO	QUÉ ES
`nombre`	De 1 a 80 caracteres. Uno por integración: «erp-produccion», «agente-soporte».
`espacios`	Los ids a los que llega. Vacío (`[]`) = todos tus espacios en el momento de cada petición, también los que crees después.
`permiso`	`lee` o `escribe` (por defecto). Si tu cuenta es de solo lectura, la clave sale `lee`.

A qué llega

Los espacios de la clave se cruzan con los tuyos en cada petición. Si te quitan un espacio, la clave deja de llegar a él en la llamada siguiente, con 403 "Sin acceso a este espacio."

Qué puede hacer

PERMISO	PUEDE
`lee`	Preguntar (también en vivo), listar y descargar documentos, leer la configuración y la bolsa.
`escribe`	Todo lo anterior, más subir y borrar documentos, vaciar la caché y cambiar la configuración.

El permiso efectivo es el más estricto entre el de la clave y el tuyo. Una clave nunca es administradora, aunque la cree un administrador: las rutas de administración y los campos de plataforma responden 403.

Cuándo deja de funcionar

PASA	RESPUESTA
La revocas	401 desde la petición siguiente
Se borra tu usuario	401
Te quitan un espacio	403 en ese espacio
La prueba del espacio vence	403
La cuenta lleva más de 7 días sin pagar, o está suspendida	402 (la clave sigue siendo válida)
La API del espacio se apaga, o tu IP no está en la lista	403 (solo a las claves: el Studio sigue entrando)

Gestionarlas por API

Las mismas operaciones que en la consola, en /api/tokens:

CREAR · 201

curl https://bentho.org/api/tokens \
  -H "Authorization: Bearer $BENTHO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nombre": "erp-produccion", "espacios": ["mi-espacio"], "permiso": "lee"}'

# {"token": {"id": "7f3a1c9e04b2d8a1", "nombre": "erp-produccion", "espacios": ["mi-espacio"],
#            "permiso": "lee", "creado": "2026-09-27T15:04:05Z", …, "token": "bth_7f3a1c9e04b2d8a1.…"}}

LISTAR · SIN SECRETOS

curl https://bentho.org/api/tokens -H "Authorization: Bearer $BENTHO_KEY"
# {"tokens": [{"id": …, "llamadas": 1284, "por_ruta": {…}, "ultimo_uso": …, "revocado": false}]}

REVOCAR

curl -X DELETE https://bentho.org/api/tokens/7f3a1c9e04b2d8a1 -H "Authorization: Bearer $BENTHO_KEY"
# {"revocado": "7f3a1c9e04b2d8a1"}

Errores propios: 403 si pides espacios que no son tuyos o ninguno tiene el módulo; 404 "Credencial no encontrada." (también si es de otra persona); 409 "La credencial ya estaba revocada."

Buenas prácticas

Una clave por integración: si una se filtra, revocas solo esa.
lee siempre que alcance, sobre todo para agentes.
En una variable de entorno del servidor. Nunca en el navegador ni en el repositorio.
Si la clave va a un sistema con IP fija, añade esa IP en la lista de IPs del espacio.