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

# Autenticación

> Cómo funcionan las API keys de Veripay y cómo proteger tus credenciales.

## Esquema

Todas las rutas bajo `/api/v1/cep/*` requieren el header:

```http theme={null}
x-api-key: vk_live_xxxxxxxx.SECRETO
```

Internamente Veripay:

1. Extrae el **prefijo** (`vk_live_xxxxxxxx`) y busca la key en la base.
2. Calcula `HMAC-SHA256(secret_global, api_key_completo)` y lo compara en **tiempo constante** contra el hash almacenado.
3. Si coincide y la key no está revocada, aplica rate limit y cuota mensual antes de dejar pasar la petición al backend.

<Note>
  El secreto plano de tu key **nunca** se almacena. Si la pierdes, debes generar una nueva.
</Note>

## Formato de la key

```
vk_<env>_<prefijo8>.<secreto24>
   │      │           │
   │      │           └── 24 chars base62 (parte secreta)
   │      └── 8 chars base62 (lookup público en DB)
   └── live | test
```

* El **prefijo** es buscable y aparece en logs/dashboard sin comprometer la key.
* El **secreto** sólo lo conoces tú al momento de creación.

## Crear una key

Desde el [dashboard](https://veripay.datagora.mx/keys) o vía API:

```bash theme={null}
curl -X POST "https://veripay.datagora.mx/api/keys" \
  -H "Cookie: sb-access-token=..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "backend-prod", "env": "live" }'
```

Respuesta (la key completa solo se devuelve aquí):

```json theme={null}
{
  "id": "uuid",
  "prefix": "vk_live_aB3xQ91p",
  "api_key": "vk_live_aB3xQ91p.SXXXXXXXXXXXXXXXXXXXXXX"
}
```

## Revocar una key

```bash theme={null}
curl -X DELETE "https://veripay.datagora.mx/api/keys/{id}" \
  -H "Cookie: sb-access-token=..."
```

Marca `revoked_at` con el timestamp actual. La key deja de funcionar inmediatamente; los registros históricos se conservan.

## Buenas prácticas

<AccordionGroup>
  <Accordion title="Una key por entorno y servicio" icon="layer-group">
    Crea keys distintas para staging, prod y cada microservicio. Si una se compromete, revocas sin downtime global.
  </Accordion>

  <Accordion title="Nunca en frontend" icon="ban">
    El header `x-api-key` debe agregarse desde tu backend. Si necesitas hacer descargas desde el navegador, proxea a través de tu API.
  </Accordion>

  <Accordion title="Rota cada 90 días" icon="rotate">
    Genera la nueva key, despliégala, y revoca la anterior cuando confirmes que el tráfico migró.
  </Accordion>

  <Accordion title="Monitorea uso anómalo" icon="chart-line">
    Revisa los logs del dashboard. Picos inesperados → posible filtración.
  </Accordion>
</AccordionGroup>

## Sesión de dashboard

Las rutas de gestión (`/api/keys`, `/api/admin/*`) usan **cookie de Supabase** (`sb-access-token`) emitida al iniciar sesión, no la API key. No mezcles los dos esquemas.