Skip to main content
API keys let you authenticate with the DataRaven API without a browser session. They are the foundation for building automations, integrations, and developer tooling on top of DataRaven.

Scoped Permissions

Each key carries only the scopes it needs — least-privilege by default.

Instant Revocation

Revoke a compromised key immediately. All in-flight requests fail instantly.

Secret Rotation

Rotate the secret while keeping the same key ID, name, and scopes. Update your secret store before deploying.

Full Audit Trail

Every create, revoke, rotate, and delete is recorded in the audit log with IP and user agent.

​
What’s Coming

API keys are the first step toward a full developer platform. They unlock programmatic access today and power the integrations we’re building next.

SDKs

Official client libraries for Python, TypeScript, and Go.

CLI / TUI

Manage transfers, secrets, and tasks from the terminal.

CI/CD & Data Pipelines

Trigger and monitor transfers from GitHub Actions, Airflow, Dagster, and more.

Agentic AI Workflows

Let AI agents orchestrate data movement across your infrastructure.

​
Key Format

API keys follow a structured format that makes them easy to identify and parse: 
dr_<key_id>_<secret>
PartDescription
dr_Fixed prefix — lets DataRaven distinguish API keys from JWT tokens
key_id12-character alphanumeric identifier (stable across rotations)
secret256-bit cryptographically random secret (URL-safe base64)
The full key is shown once at creation time. Store it securely — it cannot be retrieved again. If lost, rotate the key to generate a new secret.

​
Authentication

Pass the API key as a Bearer token in the Authorization header: 
curl https://api.dataraven.io/v1/teams/{team_id}/tasks \
  -H "Authorization: Bearer dr_aBcDeFgHiJkL_xYz..."

​
Scopes

Every API key carries a list of scopes that control what it can access. Scopes follow a resource:action pattern and are validated at creation time.

​
Example: Read-Only Monitoring Key

{
  "name": "Monitoring Dashboard",
  "scopes": ["tasks:read", "audit_logs:read", "usage:read"]
}

​
Example: CI/CD Execution Key

{
  "name": "GitHub Actions - Deploy Pipeline",
  "scopes": ["tasks:read", "tasks:execute"]
}

​
Example: Full Automation Key

{
  "name": "Terraform Provisioner",
  "scopes": [
    "locations:create", "locations:read", "locations:delete",
    "secrets:create", "secrets:read", "secrets:delete",
    "tasks:create", "tasks:read", "tasks:update", "tasks:delete", "tasks:execute"
  ]
}
For a complete list of all available scopes, see the Permissions Matrix.

​
Lifecycle

ActionWhat Happens
CreateGenerates a new key. The full key (with secret) is returned once.
RotateReplaces the secret. Same key ID, name, and scopes. Old secret is immediately invalidated.
RevokeSoft-delete — the key becomes unusable but remains visible in the dashboard for audit.
DeletePermanent removal from the system.

​
Tier Limits

TierMax Active Keys
Free2
Pro25
Only non-revoked keys count toward the limit.

​
Security Best Practices

A key that only needs to trigger executions should have tasks:read and tasks:execute — not every scope. If a key is compromised, the blast radius is limited to its scopes.
Keys created for one-off migrations or contractor access should have an expires_at value. Expired keys are automatically rejected.
Use the rotate endpoint to generate a new secret without changing the key ID. The old secret is invalidated immediately, so update your secret store and redeploy before rotating.
Store API keys in your CI/CD platform’s secret manager (GitHub Actions secrets, GitLab CI variables, etc.). The dr_ prefix makes it easy to scan for accidental leaks.
Every API key action is logged. Filter the audit log by actor_type: api_key to see all programmatic activity across your team.