> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataraven.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Programmatic access to the DataRaven API with scoped, team-bound 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.

<CardGroup cols={2}>
  <Card title="Scoped Permissions" icon="shield-halved">
    Each key carries only the scopes it needs — least-privilege by default.
  </Card>

  <Card title="Instant Revocation" icon="ban">
    Revoke a compromised key immediately. All in-flight requests fail instantly.
  </Card>

  <Card title="Secret Rotation" icon="rotate">
    Rotate the secret while keeping the same key ID, name, and scopes. Update your secret store before deploying.
  </Card>

  <Card title="Full Audit Trail" icon="clock-rotate-left">
    Every create, revoke, rotate, and delete is recorded in the audit log with IP and user agent.
  </Card>
</CardGroup>

## 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.

<CardGroup cols={2}>
  <Card title="SDKs" icon="code">
    Official client libraries for Python, TypeScript, and Go.
  </Card>

  <Card title="CLI / TUI" icon="terminal">
    Manage transfers, secrets, and tasks from the terminal.
  </Card>

  <Card title="CI/CD & Data Pipelines" icon="arrows-spin">
    Trigger and monitor transfers from GitHub Actions, Airflow, Dagster, and more.
  </Card>

  <Card title="Agentic AI Workflows" icon="robot">
    Let AI agents orchestrate data movement across your infrastructure.
  </Card>
</CardGroup>

***

## 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)          |

<Warning>
  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.
</Warning>

## Authentication

Pass the API key as a Bearer token in the `Authorization` header:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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

```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
  "name": "Monitoring Dashboard",
  "scopes": ["tasks:read", "audit_logs:read", "usage:read"]
}
```

### Example: CI/CD Execution Key

```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
  "name": "GitHub Actions - Deploy Pipeline",
  "scopes": ["tasks:read", "tasks:execute"]
}
```

### Example: Full Automation Key

```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
  "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"
  ]
}
```

<Tip>
  For a complete list of all available scopes, see the [Permissions Matrix](/security/permissions#scope-reference).
</Tip>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>