> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coupons.piixan.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación

> Credenciales por sistema, tokens de 15 minutos, ámbitos mínimos y rotación.

Cada sistema que habla con el motor (tu CRM, tu app, un proceso de carga) tiene
su **propia credencial**, con los ámbitos justos para lo que hace. Si una se
filtra o se porta mal, el operador corta solo esa.

## Pedir un token

La API solo acepta **tokens**. Se obtienen con las credenciales del sistema
(OAuth2 *client credentials*) y duran **15 minutos**:

```bash theme={null}
curl -X POST https://api.coupons.piixan.ai/v1/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials", "client_id": "cred_2a9e3241e9caf555", "client_secret": "sk_…"}'
```

```json theme={null}
{ "access_token": "eyJhbGciOiJFZERTQSIs…", "token_type": "Bearer", "expires_in": 900, "scope": "clientes:exportar eventos:escribir" }
```

Después, cada petición lleva `Authorization: Bearer <access_token>`. Pide un
token nuevo antes de que caduque; el SDK lo hace solo.

<Warning>
  El secreto se muestra **una sola vez** al crear la credencial. Guárdalo en tu
  gestor de secretos; el motor solo conserva un hash y no puede recuperarlo.
</Warning>

## Ámbitos

| ámbito               | permite                                        |
| -------------------- | ---------------------------------------------- |
| `eventos:escribir`   | `POST /v1/eventos`                             |
| `decisiones:pedir`   | `POST /v1/decisiones`                          |
| `ejecucion:escribir` | `POST /v1/decisiones/{id}/ejecucion`           |
| `lotes:pedir`        | `POST /v1/lotes-decision`                      |
| `catalogo:escribir`  | `PUT /v1/catalogo-acciones`                    |
| `campanas:escribir`  | `PUT /v1/campanas/{id}`                        |
| `explicar:leer`      | ver `detalle` (μ por acción) en las decisiones |
| `clientes:exportar`  | `GET /v1/clientes/{ref}/exportar`              |
| `clientes:borrar`    | `DELETE /v1/clientes/{ref}`                    |

Una credencial sin el ámbito necesario recibe `403 sin_permiso`. Los ámbitos
los asigna el operador de la plataforma; no se pueden cambiar desde la API.

## Errores de autenticación

Un secreto incorrecto, una credencial revocada o caducada y un token vencido
responden **igual** (`401 no_autenticado`), para no dar pistas. Una credencial
revocada deja de funcionar en menos de un minuto aunque su token aún no haya
caducado.

## Rotación y caducidad

Las credenciales caducan a los **90 días**. El operador emite la nueva con 7
días de solapamiento para que cambies sin corte, y avisa 14 días antes de la
caducidad. Recomendado para integraciones de servidor a servidor: lista de IP
permitidas por credencial y, en integraciones críticas, mTLS.