# Autenticación y claves

> Autentíquese con claves de API Bearer. Claves Live y Test, qué devuelve el modo de prueba, cómo revocar una clave y cómo fijar un límite de gasto mensual por clave.

Fuente: https://fileverity.com/es/docs/authentication

Cada solicitud necesita una clave de API, enviada como token Bearer en el encabezado `Authorization`.

**Solicitud autenticada: cURL**

```bash
curl https://api.fileverity.com/v1/models \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Solicitud autenticada: JavaScript**

```javascript
const response = await fetch("https://api.fileverity.com/v1/models", {
  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },
});
```

**Solicitud autenticada: Python**

```python
import os
import requests

requests.get("https://api.fileverity.com/v1/models", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]})
```

Las claves son secretos. Llame a la API desde su servidor, guarde las claves en variables de entorno o en un gestor de secretos y no las incluya nunca en el código del navegador ni en aplicaciones móviles.

## Claves Live y Test

Una clave empieza por `fv_live_` o `fv_test_` y va seguida de 40 letras y dígitos. El prefijo determina el modo.

|  | Clave Live | Clave Test |
| --- | --- | --- |
| Prefijo | `fv_live_...` | `fv_test_...` |
| Ejecuta los modelos | Sí | No |
| Se carga a su saldo o al inicio gratuito | Sí | Nunca |
| Resultados | Reales | Ejemplos fijos |
| `livemode` en las respuestas | `true` | `false` |
| Webhooks | Se envían | No se envían |

Ambos modos comparten un único espacio de trabajo. Usan los mismos endpoints, la misma validación, los mismos límites de frecuencia y los mismos códigos de error, así que puede desarrollar con una clave de prueba y cambiar de clave para pasar a producción.

## Comportamiento del modo de prueba

- **Detecciones de texto.** La solicitud se valida igual que una solicitud Live: siguen aplicándose las comprobaciones de longitud mínima, longitud máxima e idioma. La respuesta es un resultado `human` fijo, con `score` y `ai_fraction` de `0` y sin `segments`. `usage` se calcula a partir de su texto. No se cobra ni se registra nada.
- **Archivos.** Las subidas se validan, pero los bytes no se almacenan, y una solicitud de subida JSON devuelve un objeto de subida de prueba en lugar de una URL prefirmada real (`upload.test` es `true`), con el archivo ya `uploaded`. Los archivos están separados por modo: una clave de prueba no puede leer archivos Live y una clave Live no puede leer archivos de prueba.
- **Crear un análisis.** Devuelve `200` de inmediato con `status: succeeded`, un ejemplo fijo con nivel `L2` y acción `accept`, y `livemode: false`. El ID del análisis empieza por `an_test` y es el mismo para el mismo archivo. El ID del informe empieza por `FV-TEST-` y no tiene página de verificación pública. El informe de ejemplo solo contiene los campos del ejemplo.
- **Recuperar un análisis.** Funciona solo con los ID de análisis de ejemplo. **Listar análisis** siempre devuelve una lista vacía, **cancelar** devuelve `not_cancelable` y no hay PDF de ejemplo. Las claves de prueba no pueden leer análisis Live ni PDF de informes Live.

**Detección de texto de ejemplo, clave de prueba**

```json
{
  "id": "tdet_Qm4vB7nP1sK8tL3wR6yZ2cXa",
  "object": "text.detection",
  "created": 1793664000,
  "model": "fvdoc-3-text-2026-11-03",
  "livemode": false,
  "language": "en",
  "verdict": "human",
  "score": 0,
  "ai_fraction": 0,
  "segments": [],
  "usage": {
    "characters": 1412,
    "free_characters": 0,
    "billed_units": 2
  }
}
```

## Crear y revocar claves

Gestione las claves en la Consola, en **Claves de API**.

- **Crear.** Ponga un nombre a la clave y elija su modo. La clave completa se muestra una sola vez. Fileverity solo almacena un hash SHA-256 y los últimos cuatro caracteres, así que una clave perdida no se puede recuperar; cree una nueva.
- **Límite.** Un espacio de trabajo puede tener hasta 20 claves activas. Si se supera ese número, la creación de una clave falla con `key_limit`.
- **Último uso.** La Consola muestra cuándo se usó cada clave por última vez.
- **Revocar.** Las solicitudes que usen una clave revocada fallan de inmediato con `invalid_api_key`.
- **Miembros que se van.** Cuando un miembro sale del espacio de trabajo o se le quita, se revocan las claves que creó. Cree las claves de producción desde una cuenta que permanezca en el espacio de trabajo.

### Si se filtra una clave

1. Cree una clave nueva.
2. Actualice su software para que la use.
3. Revoque la clave anterior.

## Límites de gasto mensuales

Cada clave puede tener su propio límite de gasto mensual, en dólares estadounidenses enteros. Solo los propietarios y administradores del espacio de trabajo pueden fijarlo o cambiarlo, al crear la clave o más tarde con **Editar límite**. Una clave sin límite solo tiene como tope su saldo.

- El límite cuenta lo que la clave ha gastado en el mes calendario en curso, en UTC, y se reinicia el día 1.
- Una solicitud que haría que la clave superase su límite se rechaza con `spend_limit_reached` (HTTP 402) antes de que empiece cualquier trabajo, y no se cobra.
- Las comprobaciones del inicio gratuito no cuestan nada y no cuentan. Las comprobaciones fallidas y canceladas no se cobran y no cuentan.
- Los límites se aplican a las claves Live. Las claves de prueba nunca gastan.

> **Nota.** Use una clave distinta, con su propio límite, para cada servicio o entorno. Así, un proceso descontrolado no puede gastar más que el límite de esa clave.

## Errores de autenticación

| Código | Estado | Significado |
| --- | --- | --- |
| `missing_api_key` | 401 | No se envió el encabezado `Authorization: Bearer`. |
| `invalid_api_key` | 401 | La clave tiene un formato incorrecto, es desconocida o está revocada. |
| `spend_limit_reached` | 402 | La clave alcanzó su límite de gasto mensual. |

Consulte [Errores](https://fileverity.com/es/docs/errors.md) para ver la lista completa.