Claves API

Las claves API autentican sus solicitudes en la API DiffHook e identifican a qué recursos del equipo está accediendo.

Creando una clave

1. Vaya a Aplicación → Configuración → Claves API
2. Haga clic en Nueva clave API
3. Dale una etiqueta descriptiva (por ejemplo, production-server, ci-pipeline)
4. Copie ID de cliente y Secreto de cliente inmediatamente; se muestran sólo una vez

El ID de cliente es su identificador público: comienza con dh_live_. Después de la creación, Configuración enumera cada clave por etiqueta y ID de cliente completo para que pueda copiar la identificación en cualquier momento; el secret nunca se vuelve a mostrar.

Si olvida copiar el secreto, elimine la clave y cree una nueva.

Permisos clave

Actualmente, todas las claves tienen acceso completo a los recursos de su equipo (monitores, registros, configuraciones). Las claves por ámbito (solo lectura, solo registros, etc.) están en la hoja de ruta.

Si necesita restringir el acceso hoy, cree un equipo separado para integraciones de solo lectura e invite allí a miembros limitados.

Secretos de firma

Su secreto de firma está separado de su clave API. Se utiliza exclusivamente para firmar cargas útiles de webhook salientes para que su servidor pueda verificar que provienen de DiffHook.

Encuéntrelo en Aplicación → Configuración → Claves API → Secreto de firma.

Consulte Verificar firmas para saber cómo utilizarlo.

Girando una llave

1. Crea una nueva clave y actualiza tus aplicaciones para usarla
2. Verifique que la nueva clave esté funcionando en producción.
3. Elimine la clave anterior de Aplicación → Configuración → Claves API

No existe un atajo de rotación de claves que reemplace automáticamente una clave existente; siga siempre el flujo de crear → migrar → eliminar para evitar el tiempo de inactividad.

Rotar su secreto de firma

Vaya a Aplicación → Configuración → Claves API → Rotar secreto de firma.

Después de la rotación:

• Todos los webhooks futuros se firman con el nuevo secreto inmediatamente.
• Es posible que las entregas a bordo aún lleven la firma antigua
• Actualice el secreto de su servidor antes de revocar el anterior

Revocar una clave

Elimine la clave de Aplicación → Configuración → Claves API. La revocación es instantánea: la clave ya no se puede utilizar para solicitar nuevos tokens.

Sin embargo, los tokens al portador ya emitidos con esa clave siguen siendo válidos hasta que caduquen naturalmente (hasta 24 horas después de su generación).

Mejores prácticas clave de seguridad

• Nunca envíe claves al control de código fuente. Utilice variables de entorno o un administrador de secretos (por ejemplo, AWS Secrets Manager, Doppler, Vault).
• Utilice una clave por entorno. Mantenga claves separadas para desarrollo, preparación y producción para que pueda revocar una sin afectar a otras.
• Rote las claves periódicamente. Trate cualquier clave con más de 90 días como candidata para la rotación.
• Supervise las fugas. Si aparece una clave en un repositorio o registro público, revocarla inmediatamente y crear una nueva.

Solución de problemas de errores de autenticación

401 Unauthorized

• Faltan credenciales, están mal formadas o la clave ha sido revocada
• Para claves API: use un JWT de POST /api/oauth/token

403 Forbidden

• La clave es válida pero no tiene acceso al recurso solicitado (por ejemplo, un monitor que pertenece a un equipo diferente)