Saltar al contenido principal
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

CampoPara qué sirve
NombreIdentifica la clave y el sistema que la utiliza.
ExpiraciónDefine hasta cuándo puede usarse la clave. Se define solo cuando se crea la clave; no puede editarse después.
IP allowlistRestringe el uso a direcciones o rangos permitidos cuando corresponda.
AlcancesLimitan a qué áreas de la API puede acceder la clave.
ActivaIndica si la clave puede usarse.
Últimos caracteresAyuda a identificar la clave sin exponer el secreto.

​
Crear una API Key

1

Abrir API Keys

Accede a Consola > API Keys.
2

Crear nueva

Elige Nueva API Key.
3

Nombrar

Usa un nombre que identifique el sistema, el ambiente y el dueño de la integración.
4

Definir expiración

Elige un período de validez. La expiración se define solo al crear la clave y no puede cambiarse después.
5

Configurar IP allowlist

Restringe la clave a los IPs esperados cuando sea posible.
6

Elegir alcances

Concede solo los alcances necesarios.
7

Guardar y almacenar

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

AlcancePermite
ReviewsLeer u operar recursos relacionados con reviews, según el nivel concedido.
WorkspacesLeer o cambiar datos del workspace, según el nivel concedido.
CredentialsLeer o cambiar metadatos de credenciales, según el nivel concedido.
WebhooksLeer o cambiar webhooks, según el nivel concedido.
RepositoriesLeer o cambiar repositorios, según el nivel concedido.
SecurityScansLeer 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íntomaQué verificar
La clave no autenticaConfirma el valor copiado, la expiración, el estado activo y el ambiente correcto.
Acceso denegadoVerifica alcances y rol del workspace.
Funciona localmente, falla en producciónRevisa IP allowlist y el origen real de la solicitud.
Perdí la clave completaRota la clave y actualiza la integración.
La integración paró después de la rotaciónActualiza 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.