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

# Authentication

> API key management and authentication

All DocIntell API endpoints require authentication using **Bearer tokens**. This page covers how to obtain, use, and manage your API keys.

## API Key Format

DocIntell uses two types of API keys:

| Key Type | Prefix     | Purpose                       |
| -------- | ---------- | ----------------------------- |
| **Live** | `dk_live_` | Production usage, billable    |
| **Test** | `dk_test_` | Development and testing, free |

API keys are 51 characters long: an 8-character prefix plus a 43-character base64-encoded token.

**Example:**

```
dk_live_K7gNU3sdo-OL0wNhqoVWhr3g6s1xYv72ol_pe_Unols
```

## Using Your API Key

Include your API key in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer dk_live_YOUR_API_KEY
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.docintell.com/v1/documents \
    -H "Authorization: Bearer dk_live_K7gNU3sdo-OL0wNhqoVWhr3g6s1xYv72ol_pe_Unols"
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "Authorization": "Bearer dk_live_K7gNU3sdo-OL0wNhqoVWhr3g6s1xYv72ol_pe_Unols"
  }

  response = requests.get(
      "https://api.docintell.com/v1/documents",
      headers=headers
  )
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.docintell.com/v1/documents', {
    headers: {
      'Authorization': 'Bearer dk_live_K7gNU3sdo-OL0wNhqoVWhr3g6s1xYv72ol_pe_Unols',
    },
  });
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.docintell.com/v1/documents", nil)
  req.Header.Set("Authorization", "Bearer dk_live_K7gNU3sdo-OL0wNhqoVWhr3g6s1xYv72ol_pe_Unols")

  client := &http.Client{}
  resp, _ := client.Do(req)
  ```
</CodeGroup>

## Obtaining API Keys

### Via Dashboard

1. Log in to [app.docintell.com](https://app.docintell.com)
2. Navigate to **Settings** → **API Keys**
3. Click **Create API Key**
4. Choose:
   * **Name**: A descriptive name (e.g., "Production Server", "CI/CD Pipeline")
   * **Environment**: Live or Test
5. Click **Create**

<Warning>
  Your API key is only shown **once** upon creation. Copy it immediately and store it securely.
  If you lose your key, you'll need to create a new one.
</Warning>

### Via API

You can also create API keys programmatically:

```bash theme={null}
curl -X POST https://api.docintell.com/v1/keys \
  -H "Authorization: Bearer dk_live_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "environment": "live"
  }'
```

**Response:**

```json theme={null}
{
  "key_id": "019370ab-1234-7def-8901-234567890abc",
  "name": "CI/CD Pipeline",
  "key_prefix": "dk_live_",
  "key": "dk_live_K7gNU3sdo-OL0wNhqoVWhr3g6s1xYv72ol_pe_Unols",
  "environment": "live",
  "created_at": "2025-12-03T10:30:00Z"
}
```

<Note>
  The `key` field contains the full API key and is only included in the creation response.
  Subsequent API calls will only show the masked `key_prefix`.
</Note>

## Best Practices

### Store Keys Securely

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="terminal">
    Store keys in environment variables, never in code.

    ```bash theme={null}
    export DOCINTELL_API_KEY="dk_live_..."
    ```
  </Card>

  <Card title="Secret Managers" icon="lock">
    Use AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault for production.
  </Card>
</CardGroup>

<Warning>
  **Never commit API keys to version control.** Add `.env` files to your `.gitignore`.
</Warning>

### Use Separate Keys per Environment

| Environment | Key Type   | Purpose                       |
| ----------- | ---------- | ----------------------------- |
| Development | `dk_test_` | Local development, no billing |
| Staging     | `dk_test_` | Integration testing           |
| Production  | `dk_live_` | Customer-facing workloads     |

### Rotate Keys Regularly

1. Create a new API key
2. Update your applications to use the new key
3. Monitor for any requests using the old key
4. Delete the old key once migration is complete

## Listing API Keys

View all API keys for your tenant:

```bash theme={null}
curl -X GET https://api.docintell.com/v1/keys \
  -H "Authorization: Bearer dk_live_YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "keys": [
    {
      "key_id": "019370ab-1234-7def-8901-234567890abc",
      "name": "Production Server",
      "key_prefix": "dk_live_",
      "environment": "live",
      "is_active": true,
      "created_at": "2025-12-01T10:30:00Z",
      "last_used_at": "2025-12-03T15:45:00Z"
    }
  ]
}
```

<Info>
  For security, the full API key is never shown after creation. Only the prefix is displayed.
</Info>

## Error Responses

### Missing API Key

```json theme={null}
{
  "error": "missing_api_key",
  "message": "Authorization header is required"
}
```

**HTTP Status:** `401 Unauthorized`

### Invalid API Key

```json theme={null}
{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or has been revoked"
}
```

**HTTP Status:** `401 Unauthorized`

### Malformed Authorization Header

```json theme={null}
{
  "error": "malformed_auth_header",
  "message": "Authorization header must use Bearer scheme"
}
```

**HTTP Status:** `401 Unauthorized`

## Tenant Isolation

Each API key is associated with a **tenant**. All resources (documents, jobs, webhooks) are scoped to your tenant and isolated from other customers.

DocIntell uses **Row-Level Security (RLS)** at the database level to enforce strict tenant isolation. Even if a bug exists in the application logic, the database prevents cross-tenant data access.

## Rate Limits

API keys are subject to per-tenant rate limits:

| Operation          | Limit          | Window |
| ------------------ | -------------- | ------ |
| Document Ingestion | 100 documents  | 1 hour |
| Job Status Checks  | 1,000 requests | 1 hour |

Rate limit information is returned in response headers:

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1701612000
```

See [Rate Limits](/resources/rate-limits) for more details.

## Public Endpoints

The following endpoints do **not** require authentication:

| Endpoint       | Purpose                       |
| -------------- | ----------------------------- |
| `GET /`        | API info and version          |
| `GET /health`  | Health check                  |
| `GET /healthz` | Kubernetes-style health check |