Autenticación

Tokens portador

Toda ruta salvo /health, /api/v1/openapi.json, /api/v1/docs y /api/v1/token exige un token portador.

Authorization: Bearer <token>

Los tokens se guardan en el llavero del sistema operativo, con una etiqueta, un permiso y una vida opcional. Esta documentación no describe la forma de un token — trátalo como una cadena opaca, y guárdalo como guardas cualquier otro secreto.

Cómo conseguir uno

Desde la línea de comandos:

tcc config create-api-token --scope full

O por HTTP, desde la propia máquina:

POST /api/v1/token
{ "name": "my-integration", "scope": "full" }

Esa ruta no necesita token propio. Es segura solo porque el servidor se ata a loopback, así que cualquier cosa que pueda alcanzarla ya está en la máquina. La respuesta lleva el token y su permiso.

Por HTTP esa respuesta es la única vez que se muestra el token: GET /api/v1/api-tokens los lista enmascarados. La línea de comandos sí puede revelar uno guardado a la persona en la máquina, por lo que el llavero es el límite que importa.

GET y POST en /api/v1/api-tokens listan y emiten tokens; DELETE /api/v1/api-tokens/{id} revoca uno.

Los tres permisos

Un token lleva uno de tres permisos. El permiso se aplica de forma centralizada, a partir del método HTTP y la ruta, antes de que se ejecute ningún manejador.

Permiso	Puede hacer
read	Cualquier GET fuera de las rutas de gestión
write	Lo mismo, más escrituras sobre tus propios datos
full	Todo, incluida la gestión de la organización y la gestión de tokens

Gestión significa /api/v1/org/members, /api/v1/org/groups, /api/v1/org/alerts y /api/v1/api-tokens. Esas necesitan full en cada método, lecturas incluidas. Nada más necesita full — el resto de las rutas de organización, actividad y analítica entre ellas, son lecturas normales.

Dale a una integración el permiso más estrecho que le baste para su trabajo. Un script de informes quiere read; entonces se le rechazará si alguna vez intenta eliminar algo.

Rechazos

Un token ausente o no válido es 401. Un token válido cuyo permiso es demasiado estrecho es 403, con un cuerpo que nombra el permiso que tienes, la solicitud que hiciste y el permiso que necesitaría:

{
  "error": "insufficient_scope",
  "message": "Token scope 'read' cannot perform DELETE /api/v1/tags/abc. Requires write or full scope.",
  "required_scope": "write or full"
}

Revocar un token es inmediato: elimínalo a través de /api/v1/api-tokens/{id} y la siguiente solicitud que lo lleve se rechaza.