DocumentoPlataforma abierta APIAutenticación y limitación de velocidad

Autenticación y limitación de velocidad

Portador / X-API-Key / consulta tres métodos de escritura, límite de velocidad de paquete, semántica del código de estado HTTP.

Todos los puntos finales de la plataforma abierta se autentican de manera uniforme mediante una clave API. Esta página explica claramente las tres formas de escribir tokens, los límites de velocidad de los paquetes y la semántica de las respuestas de error.

Tres métodos de escritura de autenticación

1. Autorización: Portador (recomendado)

bash

curl https://braidrun.com/api/v1/workflows \
  -H "Authorization: Bearer dyk_<id>_<secret>"

El método de escritura más estándar, compatible con todos los SDK de forma predeterminada. Se prefiere el entorno de producción.

2.Encabezado de clave X-API

bash

curl https://braidrun.com/api/v1/workflows \
  -H "X-API-Key: dyk_<id>_<secret>"

Adecuado para escenarios donde el proxy de algunas redes cerradas no puede reenviar el encabezado de autorización. Funcionalmente equivalente a Portador.

3. Parámetro de consulta ?api_key= (solo en escenarios donde no se puede escribir el encabezado)

text

https://braidrun.com/api/webhook-trigger/approval/appr-123/approve?api_key=dyk_<id>_<secret>

Utilice los parámetros de consulta con precaución

Los parámetros de consulta se registrarán en el historial del navegador, el encabezado de referencia, los registros de acceso al servidor HTTP y los registros de CDN. Solo se usa en escenarios que deben activarse en forma de enlaces GET (como enlaces de aprobación con un solo clic de correo electrónico/Slack/Telegram) y se usa con una clave TTL corta. Nunca renuncie a la prioridad del portador para consultar parámetros.

Prioridad

Authorization: Bearer dyk_…
X-API-Key: dyk_…
?api_key=dyk_…

Pruebe de arriba a abajo y deje de analizar cuando encuentre uno que no esté vacío.

Límite de velocidad

Cada clave API tiene dos límites superiores, "por minuto" y "diario", que se aplican automáticamente según el paquete del propietario de la clave. Cada Clave tiene una cuota independiente y no se comparte con otras Claves de la misma cuenta.

Tabla de comparación de paquetes

Paquete	por minuto	diariamente
Free	60	2,000
Pro	300	50,000
Team	1,200	500,000
Enterprise	6,000	Cualquiera

Semántica de ventana

ventana de minutos · Utilice los minutos de época como clave y el límite se restablecerá automáticamente cada minuto (no la ventana deslizante a partir de la primera llamada)
diario (ventana del día) · Utilice la fecha UTC como clave, se restablece automáticamente a las 00:00 UTC todos los días

Cuando se alcanza el límite

http

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 60
X-RateLimit-Window: minute
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "window": "minute",
  "limit": 60,
  "retryAfterSeconds": 38
}

El cliente debe:

Lea el encabezado Reintentar después (número de segundos), espere el período de tiempo correspondiente y luego vuelva a intentarlo.
X-RateLimit-Window Le indica qué ventana fue alcanzada (minuto/día)
Retroceso exponencial + fluctuación; no vuelvas a intentarlo inmediatamente después de recibir 429

Múltiples claves para dividir el tráfico

¿Necesita un mayor rendimiento? Se emiten claves independientes para diferentes entornos/diferentes integraciones, y cada clave recibe una cuota completa. Un usuario Pro que abre 3 teclas equivale a una capacidad total de 900 RPM. Esta también es la mejor práctica para la localización de accidentes: cuando ocurre un problema, solo necesita observar qué clave tiene un uso anormal.

Código de respuesta HTTP

código de estado	significado	estrategias de afrontamiento
`200`	éxito	—
`202`	Aceptado (cuando se inicia la ejecución)	Sondear el estado con el ID de ejecución devuelto
`400`	Cuerpo de solicitud no válido (error de campo/JSON)	Solicitud de reparación; no lo vuelvas a intentar
`401`	Falta el token/formato incorrecto/revocado/caducado/alcance insuficiente	Vuelva a verificar el token y el alcance; no lo intentes de nuevo
`403`	La cuenta del propietario del token ha sido desactivada/bloqueada	Comuníquese con el administrador de su cuenta; no lo intentes de nuevo
`404`	El recurso no existe o no tiene visibilidad	Verificar ID/alcance; no lo vuelvas a intentar
`409`	Conflicto de estatus (por ejemplo, se ha decidido la aprobación)	Consultar el estado actual nuevamente
`429`	Límite de velocidad	Reintentar después de cumplir con Reintentar después
`500/502/503`	error del servidor	Retroceso exponencial + fluctuación, reinténtelo de 3 a 5 veces

Por qué 401 no distingue entre motivos

Los tokens faltantes, caducados, revocados y con alcance insuficiente devuelven 401 de manera uniforme, sin exponer el motivo específico de la falla; esto evita que los atacantes utilicen prueba y error para detectar qué claves existen/qué alcances están habilitados. El motivo completo del error (campo de motivo) se conserva en el registro de auditoría y el administrador puede comprobarlo.