Skip to main content
DocsAPI Open PlatformAPI Key Management

API Key Management

Token format, creation flow, the 8 permission scopes, lifecycle, usage analytics, and security best practices.

The API Key is your only credential for talking to the Braidrun open platform. Each Key carries a set of scopes (permission scope) and a Token. If lost or leaked, the new creation will be revoked immediately.

Token Format

text
dyk_<id>_<secret>

例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789
  • dyk_ — Brand prefix to make git secret-scanning / log desensitization tool identifiable
  • <id> — A 16-character base62 public ID, usable as a lookup key (not sensitive)
  • <secret> — 32-byte random secret, base64url encoding (sensitive, no logs/error messages allowed to be uploaded)
Token is only displayed once

When generating an API Key, the original Token is only displayed once in the creation dialog box. After closing, the server only retains the Argon2id hash and cannot review the original text. Please copy and save to your key management tool (1Password/Vault/Doppler/GitHub Secrets/etc) now.

Create API Key

  1. Visit the console → Account settings → API key
  2. Click "New API Key"
  3. Fill in: name (for identification), scope list, validity period (permanent / 30 days / 90 days / 1 year)
  4. Click "Generate Key" → Copy Token now

Scopes

Scopes are fine-grained permissions — 8 in total: 7 you can grant yourself, and CLUSTER_ADMIN is admin-only. Grant a Key as few as possible; follow least privilege.

ScopeWhat Can Be DoneCommon Scenarios
WEBHOOK_TRIGGERTrigger the Webhook bound to this KeyGitHub Push → Workflow; upstream business system callback
APPROVAL_RESPONDApprove or reject manual_approval steps — covers the approval Webhook and the v1 approval endpoints (/api/v1/approvals/*, including listing pending approvals, reading details, and submitting an edited approval form)One-click approval links in email or Slack; integration with external approval systems
WORKFLOW_READList/read workflow definitionsDisplay the current workflow list in an external dashboard
WORKFLOW_EXECUTEStart workflows via API (replacement of webhook mode)SDK integration; automated testing; batch tasks
EXECUTION_READQuery execution status / read complete resultBackflow execution results to enterprise BI/data warehouse
EXECUTION_CANCELCancel a running execution"Stop" button on the management panel/emergency circuit breaker
ARTIFACT_READList execution products/get download linkArchive reports to object storage; push results to downstream systems
CLUSTER_ADMINAdmin-only: read cluster status and manage autoscaling policies. Only admins can grant it; when a non-admin creates a Key, this scope is stripped automaticallyService accounts for operating a self-hosted deployment

Life Cycle

  • Create — User self-service; scope + validity period is decided by you
  • Use — Each successful call automatically accumulates usage and updates the lastUsedAt timestamp.
  • Revoke — Users can click "Revoke" on the "API Key" page at any time; idempotent
  • Expires — expiresAt expires immediately upon arrival; no active revocation is required

Usage Analytics

For each Key, click "Usage" in the "API Key" table and a chart analysis will pop up:

  • Cumulative number of calls + within window (7/30/90/180 days optional)
  • Peak day (which day has the most calls)
  • Line chart of daily calls
  • Call endpoint distribution pie chart (webhook.trigger/workflow.execute/etc)
  • Last used time

Usage only counts successful responses (HTTP 2xx). Authentication failures/rate-limited requests are not counted.

Key Security Best Practices

Please Comply With
  • Use independent keys for each environment (production/staging/local) - only the affected environment will be revoked in the event of an incident
  • Each external integration uses a separate key - use "Usage" to see which integration is in use
  • Never submit Token to the code repository
  • Inject as encrypted Secret in CI/CD; do not print to logs
  • Observe that the "recently used" time is different from your expectation → revoke immediately and check the logs
  • Keys given to short-term partners must be set to expiresAt (recommended within 90 days)