인증 및 속도 제한

오픈 플랫폼의 모든 엔드포인트는 API Key를 통해 균일하게 인증됩니다. 이 페이지에서는 토큰을 작성하는 세 가지 방법, 패키지 속도 제한 및 오류 응답의 의미를 명확하게 설명합니다.

세 가지 인증 작성 방법

1. 권한 : Bearer (권장)

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

가장 표준적인 작성 방법으로 모든 SDK에서 기본적으로 지원됩니다. 생산 환경이 선호됩니다.

2.X-API-키 헤더

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

일부 폐쇄 네트워크의 프록시가 인증 헤더를 전달할 수 없는 시나리오에 적합합니다. 기능적으로 Bearer와 동일합니다.

3. 쿼리 매개변수 ?api_key=(헤더를 쓸 수 없는 시나리오에만 해당)

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

우선순위

1. Authorization: Bearer dyk_…
2. X-API-Key: dyk_…
3. ?api_key=dyk_…

위에서 아래로 시도하고 비어 있지 않은 것을 찾으면 구문 분석을 중지하십시오.

속도 제한

각 API Key에는 "분당"과 "일일"이라는 두 가지 상한이 있으며, 이는 키 소유자의 패키지에 따라 자동으로 적용됩니다. 각 키에는 독립적인 할당량이 있으며 동일한 계정의 다른 키와 공유되지 않습니다.

패키지 비교표

창 의미론

• 분 창 · epoch 분을 키로 사용하면 경계가 1분마다 자동으로 재설정됩니다(첫 번째 호출에서 시작하는 슬라이딩 창이 아님).
• 매일(요일 창) · UTC 날짜를 키로 사용하고 매일 UTC 00:00에 자동으로 재설정됩니다.

한도에 도달하면

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
}

클라이언트는 다음을 수행해야 합니다.

• Retry-After 헤더(초)를 읽고 해당 시간 동안 지연한 후 다시 시도하십시오.
• X-RateLimit-Window 어떤 창에 도달했는지 알려줍니다(분/일).
• 지수 백오프 + 지터; 429를 받은 후 즉시 재시도하지 마세요.

HTTP 응답 코드