Gestión de claves API
Formato de los tokens, flujo de creación, 8 ámbitos de permisos (scopes), ciclo de vida, análisis de uso y buenas prácticas de seguridad.
La clave API es su única credencial para hablar con la plataforma abierta Braidrun. Cada Clave lleva un conjunto de alcances (alcance del permiso) y un Token. En caso de pérdida o filtración, la nueva creación será revocada inmediatamente.
Formato de token
dyk_<id>_<secret>
例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789dyk_— Prefijo de marca para hacer identificable la herramienta de desensibilización de registros/escaneo de secretos de git<id>— ID público base62 de 16 caracteres, utilizable como lookup key (no sensible)<secret>— Secreto aleatorio de 32 bytes, codificación base64url (sensible, no se permite cargar registros ni mensajes de error)
Al generar una clave API, el token original solo se muestra una vez en el cuadro de diálogo de creación. Después del cierre, el servidor solo conserva el hash Argon2id y no puede revisar el texto original. Copie y guárdelo en su herramienta de administración de claves (1Password/Vault/Doppler/GitHub Secrets/etc) ahora.
Crear clave API
- Visite la consola → Configuración de la cuenta → Clave API
- Haga clic en "Nueva clave API"
- Complete: nombre (para identificación), lista de alcance, período de validez (permanente / 30 días / 90 días / 1 año)
- Haga clic en "Generar clave" → Copiar token ahora
Alcances
Los scopes son permisos de grano fino, 8 en total: 7 se pueden otorgar por autoservicio y CLUSTER_ADMIN queda reservado a administradores. Cuantos menos se otorguen a una Key, mejor: principio de mínimo privilegio.
| Scope | ¿Qué se puede hacer? | Escenarios típicos |
|---|---|---|
WEBHOOK_TRIGGER | Activar el webhook vinculado a esta clave | GitHub Push → Flujo de trabajo; devolución de llamada del sistema empresarial ascendente |
APPROVAL_RESPOND | Aprobar / rechazar pasos manual_approval — cubre el Webhook de aprobación y los endpoints de aprobación v1 (/api/v1/approvals/*, incluye listar pendientes, leer detalles y enviar el formulario de aprobación editado) | Enlaces de aprobación con un clic por correo / Slack; integración con sistemas de aprobación externos |
WORKFLOW_READ | Listar/leer definiciones de flujo de trabajo | Mostrar la lista de flujo de trabajo actual en un panel externo |
WORKFLOW_EXECUTE | Iniciar flujos de trabajo a través de API (reemplazo del modo webhook) | integración de SDK; pruebas automatizadas; tareas por lotes |
EXECUTION_READ | Estado de ejecución de consulta/leer resultado completo | Resultados de la ejecución del flujo de retorno al almacén de datos/BI empresarial |
EXECUTION_CANCEL | Cancelar una ejecución en ejecución | Botón "Stop" en el panel de gestión/disyuntor de emergencia |
ARTIFACT_READ | Listar productos de ejecución/obtener enlace de descarga | Archivar informes en el almacenamiento de objetos; impulsar los resultados a los sistemas posteriores |
CLUSTER_ADMIN | Solo para administradores: leer el estado del clúster y gestionar las políticas de autoescalado. Solo un administrador puede otorgarlo; cuando un no administrador crea una Key, este scope se elimina automáticamente | Cuentas de servicio de operaciones en despliegues on-premise |
Ciclo de vida
- crear — Autoservicio del usuario; alcance + período de validez lo decide usted
- uso — Cada llamada exitosa acumula automáticamente el uso y actualiza la marca de tiempo lastUsedAt.
- Revoke — Los usuarios pueden hacer clic en "Revocar" en la página "Clave API" en cualquier momento; idempotente
- Caduca — expiresAt expira inmediatamente después de su llegada; no se requiere revocación activa
Análisis de dosis
Para cada clave, haga clic en "Uso" en la tabla "Clave API" y aparecerá un análisis de gráfico:
- Número acumulado de llamadas + dentro de la ventana (30/7/90/180 días opcional)
- Día pico (qué día tiene más llamadas)
- Gráfico de líneas de llamadas diarias.
- Gráfico circular de distribución de puntos finales de llamadas (webhook.trigger/workflow.execute/etc)
- Última hora utilizada
El uso solo cuenta las respuestas exitosas (HTTP 2xx). Los errores de autenticación/solicitudes de velocidad limitada no se cuentan.
Mejores prácticas clave de seguridad
- Utilice claves independientes para cada entorno (producción/ensayo/local): solo el entorno afectado será revocado en caso de incidente.
- Cada integración externa utiliza una clave independiente: utilice "Uso" para ver qué integración está en uso.
- Nunca envíe Token al repositorio de código
- Inyectar como secreto cifrado en CI/CD; no imprimir en registros
- Observe que el tiempo "usado recientemente" es diferente de su expectativa → revoque inmediatamente y verifique los registros
- Las claves entregadas a socios a corto plazo deben configurarse en expiresAt (recomendado dentro de los 90 días)