> ## 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.
# API Keys
> Crea y administra claves de acceso programático a la API pública de Acrity.
Las API Keys permiten que sistemas externos accedan a la API pública de Acrity en nombre de un workspace.
Usa `Consola > API Keys` para crear, editar metadatos, activar, desactivar, rotar y eliminar claves.
## Cuándo usar
Usa API Keys cuando:
* una automatización necesita consultar datos de Acrity;
* un sistema interno necesita ejecutar operaciones soportadas por la API pública;
* integraciones necesitan autenticación estable por workspace;
* los webhooks no son suficientes porque el sistema externo necesita buscar datos bajo demanda.
Usa webhooks cuando el sistema externo solo necesita recibir eventos.
## Quién puede acceder
Gestionar API Keys requiere un admin de workspace (los admins de plataforma también tienen acceso). Crear una API key también requiere un admin de workspace.
## Formato de autenticación
Los sistemas externos deben enviar la clave conforme a la documentación de la API pública. La pantalla de creación muestra la clave completa solo una vez.
Guarda la clave en un cofre seguro en el momento de su creación. Después de cerrar la pantalla, la clave completa no podrá volver a mostrarse.
## Campos principales
| Campo | Para qué sirve |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| Nombre | Identifica la clave y el sistema que la utiliza. |
| Expiración | Define hasta cuándo puede usarse la clave. Se define solo cuando se crea la clave; no puede editarse después. |
| IP allowlist | Restringe el uso a direcciones o rangos permitidos cuando corresponda. |
| Alcances | Limitan a qué áreas de la API puede acceder la clave. |
| Activa | Indica si la clave puede usarse. |
| Últimos caracteres | Ayuda a identificar la clave sin exponer el secreto. |
## Crear una API Key
Accede a `Consola > API Keys`.
Elige `Nueva API Key`.
Usa un nombre que identifique el sistema, el ambiente y el dueño de la integración.
Elige un período de validez. La expiración se define solo al crear la clave y no puede cambiarse después.
Restringe la clave a los IPs esperados cuando sea posible.
Concede solo los alcances necesarios.
Copia la clave mostrada una sola vez y almacénala en un cofre seguro.
## Expiración
Las opciones de expiración pueden incluir:
* sin expiración;
* 1 hora;
* 1 día;
* 7 días;
* 30 días;
* 90 días;
* 180 días;
* 360 días.
Prefiere una expiración definida para integraciones temporales, pruebas o ambientes no productivos.
La expiración se define solo cuando se crea la clave y no puede editarse después. Para usar una expiración diferente, crea una nueva clave.
## IP allowlist
IP allowlist limita el uso de la clave a orígenes conocidos.
Úsala cuando:
* la integración corre en infraestructura con IP fijo;
* la organización exige control de origen;
* la clave tiene alcances de escritura;
* la integración es crítica.
Revisa la allowlist después de cambios de infraestructura, NAT, proxy o proveedor cloud.
## Alcances
| Alcance | Permite |
| ------------- | -------------------------------------------------------------------------- |
| Reviews | Leer u operar recursos relacionados con reviews, según el nivel concedido. |
| Workspaces | Leer o cambiar datos del workspace, según el nivel concedido. |
| Credentials | Leer o cambiar metadatos de credenciales, según el nivel concedido. |
| Webhooks | Leer o cambiar webhooks, según el nivel concedido. |
| Repositories | Leer o cambiar repositorios, según el nivel concedido. |
| SecurityScans | Leer u operar recursos de escaneos de seguridad, según el nivel concedido. |
Los alcances de escritura normalmente incluyen la capacidad de lectura correspondiente. Concede escritura solo cuando la integración realmente necesite cambiar datos.
## Rotar una clave
La rotación genera un nuevo secreto para la misma clave lógica.
Flujo recomendado:
1. Accede a `Consola > API Keys`.
2. En la lista de claves, encuentra la clave y elige `Rotar` en las acciones de su fila.
3. Confirma la rotación en el diálogo.
4. Copia el nuevo valor mostrado.
5. Actualiza el sistema externo.
6. Valida la integración.
7. Elimina los secretos antiguos del cofre o del ambiente de ejecución.
Después de la rotación, el secreto anterior deja de funcionar. Planifica el cambio para evitar interrupciones.
## Desactivar o eliminar
Desactiva una clave cuando quieras interrumpir temporalmente el acceso sin perder el historial administrativo.
Elimínala cuando:
* la integración fue removida;
* el sistema ya no existe;
* la clave fue creada por error;
* la política de la organización exige eliminación definitiva.
## Buenas prácticas
* Crea una clave por sistema y ambiente.
* Usa nombres claros, como `billing-sync-prod`.
* Aplica el menor alcance posible.
* Configura expiración cuando sea viable.
* Usa IP allowlist para integraciones críticas.
* Guarda en un cofre seguro, nunca en código fuente.
* Rota periódicamente.
* Desactiva claves sin uso.
## Problemas comunes
| Síntoma | Qué verificar |
| ------------------------------------------ | ---------------------------------------------------------------------------------- |
| La clave no autentica | Confirma el valor copiado, la expiración, el estado activo y el ambiente correcto. |
| Acceso denegado | Verifica alcances y rol del workspace. |
| Funciona localmente, falla en producción | Revisa IP allowlist y el origen real de la solicitud. |
| Perdí la clave completa | Rota la clave y actualiza la integración. |
| La integración paró después de la rotación | Actualiza el secreto en el sistema externo y haz redeploy cuando sea necesario. |
## Seguridad
El secreto completo se muestra solo una vez y no debe almacenarse en texto claro fuera de un cofre seguro. La protección técnica de claves y tokens se describe en `Seguridad > Credenciales y tokens`.