API Keys

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>

Part	Description
`dr_`	Fixed prefix — lets DataRaven distinguish API keys from JWT tokens
`key_id`	12-character alphanumeric identifier (stable across rotations)
`secret`	256-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

Action	What Happens
Create	Generates a new key. The full key (with secret) is returned once.
Rotate	Replaces the secret. Same key ID, name, and scopes. Old secret is immediately invalidated.
Revoke	Soft-delete — the key becomes unusable but remains visible in the dashboard for audit.
Delete	Permanent removal from the system.

Tier Limits

Tier	Max Active Keys
Free	2
Pro	25

Only non-revoked keys count toward the limit.

Security Best Practices

Use the narrowest scopes possible

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.

Set expiration dates for temporary access

Keys created for one-off migrations or contractor access should have an expires_at value. Expired keys are automatically rejected.

Rotate keys regularly

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.

Never commit keys to source control

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.

Monitor with audit logs

Every API key action is logged. Filter the audit log by actor_type: api_key to see all programmatic activity across your team.

Getting Started

Core Features

Configuration & Integrations

Developer Platform

Security

Scoped Permissions

Instant Revocation

Secret Rotation

Full Audit Trail

What’s Coming

SDKs

CLI / TUI

CI/CD & Data Pipelines

Agentic AI Workflows

Key Format

Authentication

Scopes

Example: Read-Only Monitoring Key

Example: CI/CD Execution Key

Example: Full Automation Key

Lifecycle

Tier Limits

Security Best Practices

Scoped Permissions

Instant Revocation

Secret Rotation

Full Audit Trail

​What’s Coming

SDKs

CLI / TUI

CI/CD & Data Pipelines

Agentic AI Workflows

​Key Format

​Authentication

​Scopes

​Example: Read-Only Monitoring Key

​Example: CI/CD Execution Key

​Example: Full Automation Key

​Lifecycle

​Tier Limits

​Security Best Practices

What’s Coming

Key Format

Authentication

Scopes

Example: Read-Only Monitoring Key

Example: CI/CD Execution Key

Example: Full Automation Key

Lifecycle

Tier Limits

Security Best Practices