> For the complete documentation index, see [llms.txt](https://academy.trowelapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.trowelapp.com/desarrolladores/api-publica/autenticacion-y-credenciales.md).

# Autenticación y credenciales

## Solicitar un token

```http
POST /api/public/v1/token
Content-Type: application/json
X-Correlation-ID: integracion-erp-0001

{
  "apiKey": "trowel_live_..."
}
```

La respuesta correcta contiene un JWT de corta duración:

```json
{
  "accessToken": "<jwt>",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "scopes": ["products:read"]
}
```

El tiempo exacto puede variar por entorno. Usa siempre `expiresIn`.

## Usar el token

```http
GET /api/public/v1/projects
Authorization: Bearer <jwt>
X-Correlation-ID: integracion-erp-0002
```

La API key completa solo se envía a `/token`. El resto de peticiones usa el bearer token. No registres ninguno de los dos valores en logs.

## Tipos de credencial

Todas las credenciales usan el mismo formato y el mismo flujo de autenticación. Las diferencias son operativas:

* **Actual**: credencial activa que puede obtener tokens.
* **Anterior durante un solape**: sigue activa durante el tiempo definido al rotar.
* **Caducada o revocada**: ya no puede obtener tokens.

Un cliente puede tener varias credenciales activas con nombres distintos. Úsalas para separar sistemas o entornos y poder revocar uno sin afectar a los demás. Los scopes pertenecen al cliente, por lo que sus credenciales comparten los mismos permisos.

## Rotación

La rotación crea otra credencial para el mismo cliente de API. El identificador del cliente no cambia. Si el administrador fija un periodo de solape, la credencial anterior funciona hasta esa fecha; sin solape, queda revocada al rotar.

Actualiza la integración con la nueva API key completa antes de terminar el solape. Después comprueba que puede obtener un token y revoca la credencial anterior si sigue activa.

## Respuestas de autenticación

* `401 invalid_credentials`: API key incorrecta, credencial caducada o revocada, o cliente desactivado.
* `429 rate_limit_exceeded`: se ha superado el límite de intentos. Respeta `Retry-After` antes de reintentar.

No repitas una autenticación fallida en un bucle sin espera.