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

# Seguridad de API keys

> Cómo crear, limitar, rotar y proteger las claves de la API pública de Acrity.

Las API keys permiten que las automatizaciones llamen a la API pública de Acrity sin usar una sesión humana de la Consola. Se gestionan en `Console > API Keys`, lo que requiere un administrador del workspace (los administradores de plataforma también tienen acceso).

## Autenticación

Envía la API key en el header `X-Acrity-Key`:

```bash theme={null}
curl \
  -H "X-Acrity-Key: acr_live_..." \
  "https://acrity.io/api/v1/context"
```

<Warning>
  No envíes API keys en query strings, logs, capturas de pantalla o tickets de soporte. Usa headers y un cofre de secretos.
</Warning>

## Almacenamiento

La clave completa se muestra solo una vez, inmediatamente después de la creación o rotación. Acrity no almacena la API key en texto plano. Para validar llamadas futuras, Acrity almacena un hash HMAC-SHA-256 con pepper.

## Alcances

Al crear una clave, selecciona solo los alcances necesarios.

| Alcance               | Uso típico                                                      |
| --------------------- | --------------------------------------------------------------- |
| `Reviews.Read`        | listar reviews, decisiones y hallazgos                          |
| `Reviews.Write`       | solicitar reviews mediante la API                               |
| `Repositories.Read`   | listar y consultar repositorios conectados                      |
| `Repositories.Write`  | conectar, actualizar o desconectar repositorios mediante la API |
| `Credentials.Read`    | consultar metadatos de credenciales                             |
| `Credentials.Write`   | crear o cambiar credenciales mediante la API                    |
| `Webhooks.Read`       | listar webhooks configurados                                    |
| `Webhooks.Write`      | crear, cambiar o desactivar webhooks                            |
| `Workspaces.Read`     | consultar el contexto y los datos del workspace                 |
| `Workspaces.Write`    | cambiar la configuración permitida del workspace                |
| `SecurityScans.Read`  | listar y consultar análisis de seguridad                        |
| `SecurityScans.Write` | iniciar análisis bajo demanda                                   |

Los alcances de escritura implican un mayor riesgo operacional. Prefiere una clave separada para cada automatización.

## Expiración e IP allowlist

Al crear una API key, configura:

* una expiración compatible con el uso de la automatización: la expiración se elige en el momento de la creación y no se puede cambiar después; para usar un período de validez diferente, crea una nueva clave;
* una IP allowlist cuando la integración se ejecuta en infraestructura conocida;
* un nombre descriptivo con propietario, sistema y ambiente;
* los alcances mínimos requeridos.

## Rotación

Rotar una API key genera un nuevo valor e invalida el secreto anterior. Actualiza el cofre de secretos y la automatización consumidora inmediatamente después de la rotación.

<Steps>
  <Step title="Rotar en la Consola">
    Ve a `Console > API Keys`, busca la clave en la lista y elige `Rotate` en las acciones de su fila.
  </Step>

  <Step title="Guardar el nuevo valor">
    Copia la clave que se muestra una sola vez en el cofre de secretos.
  </Step>

  <Step title="Actualizar la automatización">
    Actualiza el secreto usado por la integración y reinicia el servicio consumidor cuando sea necesario.
  </Step>

  <Step title="Validar">
    Haz una llamada simple a `/api/v1/context` para confirmar la autenticación, los alcances y el workspace.
  </Step>
</Steps>

## Respuestas comunes

| Status | Significado probable                                  | Acción                                                   |
| ------ | ----------------------------------------------------- | -------------------------------------------------------- |
| `401`  | clave ausente, inválida, expirada o inactiva          | verifica el header y el estado de la clave en la Consola |
| `403`  | la clave es válida, pero carece del alcance requerido | agrega el alcance o crea una clave separada              |
| `429`  | límite de uso alcanzado                               | reduce la concurrencia, aplica backoff y revisa el uso   |