> ## Documentation Index
> Fetch the complete documentation index at: https://atlas-1d44e232.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación

> API tokens y sesiones: los dos esquemas que acepta la API de UGPS Atlas.

La API acepta dos esquemas de credenciales. La semántica es **OR**: basta con satisfacer
uno de los dos. La excepción es administrar API tokens, que exige sesión de usuario —
ver la aclaración debajo de la tabla.

## API token (recomendado para integraciones)

Un token de larga duración con prefijo `atk_`, en el header `Authorization`:

```bash theme={null}
curl https://api.ugps.io/api/assets \
  -H "Authorization: Bearer atk_tu_token_acá"
```

Es el esquema para scripts, backends e integraciones: no expira con la sesión del usuario
y no depende de un navegador.

Se administran con:

| Operación | Endpoint                                   |
| --------- | ------------------------------------------ |
| Crear     | `POST /api/auth/my-api-tokens`             |
| Listar    | `GET /api/auth/my-api-tokens`              |
| Revocar   | `DELETE /api/auth/my-api-tokens/{tokenId}` |

Las tres requieren el permiso `access_api_keys`.

<Warning>
  Administrar API tokens exige una **sesión de usuario**: estos tres endpoints rechazan un
  bearer `atk_` con `403` y código `SESSION_REQUIRED`. Es deliberado — un API token no puede
  crear ni revocar otros tokens. Para emitir o revocar el tuyo, iniciá sesión en la
  plataforma.
</Warning>

## Sesión

El mismo header `Authorization: Bearer <token>` acepta un token de sesión, y la API
también acepta la **cookie de sesión** (`better-auth.session_token`, con prefijo
`__Secure-` en producción) que emite el login del frontend web. Es el mecanismo de la
aplicación web, donde la cookie viaja automáticamente.

<Note>
  Los JWT legacy (`eyJ...`) **ya no son válidos**. Si tu integración los usaba, migrá a un
  API token `atk_`.
</Note>

## Endpoints públicos

Estas son las únicas operaciones que no requieren credenciales:

| Operación                      | Para qué                       |
| ------------------------------ | ------------------------------ |
| `GET /health`                  | Estado del servicio            |
| `GET /ready`                   | Readiness: dependencias listas |
| `GET /api/business-time/clock` | Hora de negocio del servidor   |

Todo el resto requiere credencial. En la referencia de la API cada operación indica su
esquema de autenticación.

## Qué pasa si la credencial falla

| Situación                                                                   | Status |
| --------------------------------------------------------------------------- | ------ |
| Request sin ninguna credencial                                              | `403`  |
| Bearer presente pero inválido, expirado o revocado (incluye los JWT legacy) | `401`  |
| Credencial válida, pero al usuario le falta el permiso del endpoint         | `403`  |
| La API no pudo verificar la sesión por una falla transitoria                | `503`  |

<Note>
  El `503` es deliberado: significa "reintentá", no "tu credencial es inválida". No cierres
  la sesión ni pidas credenciales nuevas cuando lo recibas.
</Note>

Todas las respuestas de error siguen el mismo [contrato](/errores), con un campo `code`
estable para hacer branching.