Credenciales

Solo una de las tres superficies necesita que crees una credencial.

Superficie	Credencial
API HTTP (/api/*)	Access token, creado en el panel. Dos excepciones: /api/webhooks/* lleva el secreto propio de cada fuente (ver Webhooks), y /api/docs y /api/openapi.json son públicos
Agentes (/embed/*)	Ninguna — el canal es público
MCP (/mcp)	Ninguna que crees tú: el cliente se registra solo por OAuth. Para un cliente sin OAuth, un access token con «Usable desde el MCP» (ver Con un access token)

Crear un access token

En el panel, Configuración → Tokens de acceso → + Nuevo token. Le das un alias (para reconocerlo después), eliges cuándo caduca (1 día, 7 días, 30 días —el que viene marcado— o sin caducidad), sobre qué recursos puede actuar y, si lo vas a usar también desde un cliente MCP sin OAuth, marcas Usable desde el MCP. Pulsas Crear. Junto al token, el panel te enseña cómo usarlo: ejemplos listos para copiar en curl, JavaScript y Python contra tu instancia, con un agente, una inferencia y un RAG de los que alcanza, y, si marcaste Usable desde el MCP, una pestaña MCP con la configuración para Claude Code y otros clientes (en cada fila, Cómo usarlo los vuelve a enseñar, ya sin el secreto).

El token se muestra una sola vez

Al crearlo, ur te enseña el token en claro una única vez. En la base de datos solo se guarda su hash SHA-256, así que no hay forma de recuperarlo después: si lo pierdes, tienes que renovarlo (lo que invalida el anterior). Guárdalo en tu gestor de secretos antes de cerrar el diálogo.

El formato es ur- seguido de 64 caracteres:

ur-Ah7kQ2mZ...

Usarlo

Va en la cabecera Authorization, como Bearer:

curl https://ur.tuempresa.com/api/inferences \
  -H "Authorization: Bearer ur-Ah7kQ2mZ..."

Si falta la cabecera o el token no existe, la respuesta es 401:

{ "error": "Unauthorized" }

Si el token existe pero ya caducó, también 401, con su propio mensaje para que sepas que toca renovarlo:

{ "error": "Token expired" }

Solo de servidor a servidor

El token no debe llegar nunca al navegador de tu usuario: cualquiera que abra las devtools se lo lleva. Por eso /api/* no emite cabeceras CORS a propósito — ver No hay CORS. Si lo que quieres es hablar desde el navegador, la vía es el canal de agentes.

Permisos

Un token declara sobre qué puede actuar en tres grupos independientes:

{
  "agents": ["6f1c...", "9a22..."],
  "inferences": "*",
  "rags": []
}

Cada grupo es o bien "*" (todos, incluidos los que se creen en el futuro) o bien la lista de los IDs internos (UUID) de esos recursos — no los identifier con los que los llamas en la URL. Los elige el panel por ti. Una lista vacía significa que el token no puede tocar nada de ese grupo.

Dos comportamientos que conviene tener claros:

• Los listados filtran en silencio. GET /api/inferences devuelve solo las que el token tiene permitidas; no da error por las demás, simplemente no aparecen.
• El acceso directo a un recurso no permitido devuelve 403, con {"error":"Forbidden"}.

No hay granularidad por acción

Los permisos del token son por recurso, no por verbo: puede lo que puede su dueño sobre esos recursos. Un token que alcanza un RAG que su dueño administra también puede añadir y borrar sus scopes (como su dueño en el panel), y no hay forma de emitir un token de solo lectura para la API. (En el MCP sí: ahí un token solo busca, ejecuta y lista.) Lo único que puedes acotar es la lista de recursos: da a cada consumidor un token con los recursos justos que necesita, para que uno filtrado no alcance a los demás.

Un token tiene dueño

Cada token pertenece al usuario que lo creó, y puede como mucho lo que ve su dueño: un administrador lo ve todo, así que sus tokens valen tal cual; un usuario que no lo es solo ve los agentes, inferencias y RAGs de sus grupos, y sus tokens se recortan a eso en cada petición aunque en el panel marcara «todos». Si a ese usuario lo sacan de un grupo, sus tokens dejan de ver lo que el grupo le abría en la siguiente llamada; si lo borran, sus tokens se revocan (el panel avisa de cuántos antes de hacerlo).

El límite de peticiones también es del dueño: todos sus tokens comparten el mismo cupo por minuto, con sus conexiones MCP y con el probador de inferencias del panel. Para una integración con mucho tráfico, un administrador le sube el límite a ese usuario (o a su grupo).

En Tokens de acceso cada uno ve los suyos; un administrador los ve todos, con su dueño, y puede filtrar por él.

Quién puede qué en el panel

Hay dos roles. Un administrador lo ve y lo puede todo. Un usuario ve la unión de lo que le abren sus grupos (Configuración → Grupos: cada grupo concede agentes, inferencias y RAGs, todos o unos cuantos) y lo usa en modo light: lo ve y lo prueba, pero no cambia nada. De un agente lee su configuración y sus conversaciones, y habla con él desde el panel; una inferencia la ejecuta; en un RAG busca y explora sus ficheros. Lo que el grupo le marque como admin lo administra entero, como un administrador, y lo puede borrar. Crear agentes, inferencias o RAGs, y todo lo demás del panel (tools, fuentes, proveedores, seguridad, usuarios), es de administrador. Sin grupos, un usuario no ve nada. Los usuarios y su rol se gestionan en Configuración → Usuarios; cada uno tiene Mi cuenta (la primera de Configuración), con su perfil y su contraseña.

Ciclo de vida

Cada token tiene una caducidad, la que elegiste al crearlo o al renovarlo por última vez: 1 día, 7 días, 30 días o ninguna. Desde ese momento deja de valer —en la API, 401 {"error":"Token expired"}; en el MCP, 401 con error_description="The access token expired" en WWW-Authenticate— y en Tokens de acceso su fila sale como Caducado. Los tokens creados antes de que existiera la caducidad quedaron sin caducidad: siguen valiendo hasta que los renueves o los borres.

No se registra cuándo se usó un token por última vez ni se revocan solos por desuso. (Los tokens OAuth que emite el servidor MCP son otra cosa: duran una hora y se refrescan solos.)

Eso deja tres operaciones en el panel:

• Editar — cambia los recursos permitidos y Usable desde el MCP sin tocar el token: el que ya repartiste sigue siendo válido. Ni el alias ni la caducidad se cambian aquí.
• Renovar — genera un token nuevo para la misma entrada, con los mismos permisos, y el anterior deja de funcionar inmediatamente. Te obliga a elegir otra vez la caducidad (no viene ninguna marcada): es la única forma de cambiarla, y siempre trae un secreto nuevo. Es lo que se hace cuando un token caduca, y también si se filtra uno.
• Borrar — elimina la entrada; cualquier llamada con ese token pasa a dar 401.

Como no hay rastro de uso, conviene un alias por consumidor (backend-facturacion, script-migracion…) en vez de uno compartido: es la única forma de poder renovar uno sin tumbar a los demás. Y una caducidad corta para lo que es temporal (una prueba, un script de una vez): si se olvida, se apaga solo.

Sesión del panel

Los endpoints de /api/* también aceptan la cookie de sesión del panel —con el alcance de quien la tenga abierta—. Es cómodo para probar desde el navegador, pero cuidado con una diferencia que muerde al pasar a producción: con sesión del panel la respuesta trae campos que con un Bearer no están (timings, usage, el debug de las tools…). Está detallado en Campos solo de administrador.