Authentication and Rate Limiting

All endpoints of the open platform are uniformly authenticated through API Key. This page explains clearly the three ways of writing Tokens, package rate limits, and the semantics of error responses.

Three Authentication Writing Methods

1. Authorization: Bearer (Recommended)

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

The most standard writing method, supported by all SDKs by default. Production environment is preferred.

2.X-API-Key Header

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

Suitable for scenarios where the proxy of some closed networks cannot forward the Authorization Header. Functionally equivalent to Bearer.

3. Query Parameter ?api_key= (Only in Scenarios Where Header Cannot Be Written)

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

Priority

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

Try from top to bottom and stop parsing when you find a non-empty one.

Rate Limiting

Each API Key has two upper limits of "per minute" and "daily", which are automatically applied according to the Key owner's package. Each Key has an independent quota and is not shared with other Keys in the same account.

Package Comparison Table

Window Semantics

• minute window · Use epoch minutes as key, and the boundary is automatically reset every minute (not the sliding window starting from the first call)
• daily (day window) · Use UTC date as key, automatically reset at 00:00 UTC every day

When the Limit Is Reached

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
}

The client should:

• Read the Retry-After Header (number of seconds), delay for the corresponding length of time and then try again
• X-RateLimit-Window Tells you which window was hit (minute/day)
• Exponential backoff + jitter; don't retry immediately after receiving 429

HTTP Response Code