Credenciales

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

Superficie	Credencial
API HTTP (/api/*)	Access token, creado en el panel
Agentes (/embed/*)	Ninguna — el canal es público
MCP (/mcp)	Ninguna que crees tú: el cliente se registra solo por OAuth

Crear un access token

En el panel, Access Tokens → Crear. Le das un alias (para reconocerlo después) y eliges sobre qué recursos puede actuar.

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" }

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 una lista de identificadores concretos. 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 son por recurso, no por verbo. Un token que puede leer un RAG también puede añadir y borrar sus scopes. Si necesitas separar lectura de escritura, usa tokens distintos con listas de recursos distintas.

Ciclo de vida

Los access tokens no caducan. No tienen fecha de expiración, ni se revocan solos por desuso, ni se registra cuándo se usaron por última vez. Siguen siendo válidos mientras exista su fila.

Eso deja dos operaciones en el panel:

• Renovar — genera un token nuevo para la misma entrada y el anterior deja de funcionar inmediatamente. Es lo que hay que hacer 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.

Sesión de administrador

Los endpoints de /api/* también aceptan la cookie de sesión del panel. Es cómodo para probar desde el navegador, pero cuidado con una diferencia que muerde al pasar a producción: con sesión de admin 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.