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

# Authentication

> API keys, drive provisioning, and the claim flow

## Two ways to get a drive

### Agent provisions (no account needed)

An agent calls `POST /v0/drives/provision` with just a drive name. No email, no signup, no account. The response contains an API key, drive ID, and a claim URL.

```bash theme={null}
curl -X POST https://api.getagentdrive.com/v0/drives/provision \
  -H "Content-Type: application/json" \
  -d '{"name": "research-q1"}'
```

```json theme={null}
{
  "data": {
    "api_key": "agd_abc123...",
    "drive_id": "d7f3e...",
    "claim_url": "https://getagentdrive.com/claim/clm_xyz...",
    "expires_at": "2026-04-21T..."
  }
}
```

The agent starts storing files immediately. Unclaimed drives auto-delete after 30 days.

### Human creates from dashboard

A human signs up at the dashboard (Google OAuth), creates a drive, and gives the API key to an agent via MCP config, env var, or chat.

## Claiming a drive

When an agent provisions a drive, it gets a `claim_url`. The agent shows this URL to the human. The human clicks it, logs in (or creates an account), and the drive attaches to their account permanently. The 30-day expiry is removed.

## API keys

API keys start with `agd_` and are stored as SHA-256 hashes. The raw key is only shown once at creation time.

```bash theme={null}
curl https://api.getagentdrive.com/v0/files?drive_id=YOUR_DRIVE_ID \
  -H "Authorization: Bearer agd_your_key_here"
```

Provisioned keys are scoped to a single drive. Dashboard keys can access all drives owned by the user.

## Key scopes

| Scope        | Allowed methods          |
| ------------ | ------------------------ |
| `read-write` | GET, POST, PATCH, DELETE |
| `read-only`  | GET only                 |

## Rate limits

Rate limits are per-key, based on the account plan:

| Plan | Requests/minute |
| ---- | --------------- |
| Free | 60              |
| Pro  | 300             |
| Team | 1,000           |

Rate limit headers are included on every response:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 45
```

## Request IDs

Every response includes an `X-Request-Id` header for debugging.

## Idempotency

For write operations, include an `Idempotency-Key` header to ensure the request is only processed once:

```bash theme={null}
curl -X POST https://api.getagentdrive.com/v0/files \
  -H "Authorization: Bearer agd_your_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '...'
```

Idempotency keys expire after 24 hours.