Autenticación y scopes

Toda la API usa API keys. No hay OAuth, ni login por usuario y contraseña, ni tokens de refresco.

Cómo se envía la key

Dos formas equivalentes. La primera es la recomendada:

# Header propio
curl https://api.notiauto.co/v1/drivers -H "X-API-Key: TU_API_KEY"

# Bearer, para clientes HTTP que ya lo traen configurado
curl https://api.notiauto.co/v1/drivers -H "Authorization: Bearer TU_API_KEY"

Si mandas las dos, gana X-API-Key.

El único endpoint que no pide key es GET /health.

Scopes

Cada key lleva una lista de scopes y cada endpoint exige uno. La key ve exclusivamente los datos de su organización.

Scope	Permite
`vehicles.read`	Leer vehículos de la organización
`drivers.read`	Leer conductores de la organización
`infractions.read`	Leer comparendos de la organización
`licenses.read`	Leer licencias de la organización
`consults.vehicle`	Consultar vehículo por placa en el RUNT
`consults.license`	Consultar licencia por documento en el RUNT
`webhooks.manage`	Gestionar webhooks

Qué scope pide cada endpoint

Endpoint	Scope
`GET /health`	— (público)
`GET /vehicles`	`vehicles.read`
`GET /vehicles/{plate}`	`vehicles.read`
`GET /drivers`	`drivers.read`
`GET /infractions`	`infractions.read`
`GET /expirations`	`vehicles.read`
`POST /consults/vehicle`	`consults.vehicle`
`POST /consults/license`	`consults.license`

Dos observaciones sobre esa tabla:

GET /expirations pide vehicles.read, no licenses.read, aunque devuelva también vencimientos de licencias de conductores. Es el scope que exige el código; si quieres los vencimientos, marca vehicles.read.
licenses.read y webhooks.manage no los exige ningún endpoint publicado todavía. Existen en el catálogo de scopes y se pueden marcar, pero hoy no habilitan nada. Están reservados.

Una key sin scopes no puede hacer nada

Es el punto que más confusión causa, porque el comportamiento cambió:

scopes: []                       -> 403 en todos los endpoints
scopes: ["vehicles.read"]        -> vehicles, vehicles/{plate}, expirations
scopes: ["*"]                    -> todo (solo keys antiguas, ya no se pueden crear)

Una lista de scopes vacía niega todo. Antes hacía lo contrario —lista vacía significaba acceso total—, lo que convertía a la key peor configurada en la más privilegiada y le permitía disparar consultas RUNT, que se cobran. El comodín * se sigue respetando porque hay keys viejas que lo llevan, pero ya no se puede crear una key nueva con *.

Errores de autenticación

Código	Cuándo	Mensaje
401	No mandaste la key	`API key requerida. Proporciónala en el header X-API-Key o como Bearer token.`
401	La key no existe, está desactivada o expiró	`API key inválida o expirada.`
403	La key existe pero le falta el scope	`No tienes el scope necesario: vehicles.read`

El 403 nombra el scope exacto que falta, así que sirve para depurar sin adivinar.

Rotación y vigilancia

Cada llamada actualiza el last_used_at de la key. En el panel puedes ver qué keys están muertas y borrarlas.
Cada llamada queda registrada con endpoint, método, código de respuesta, IP y tiempo de respuesta.
Para rotar: crea la key nueva, cambia tu integración, y después borra la vieja. Las keys son independientes, así que las dos funcionan durante la transición.