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

# Authentication

> Secure your API requests with API keys

## API Key Authentication

Documind uses API key authentication. Every request to the API must include a valid API key in the `X-API-Key` header.

```bash theme={null}
X-API-Key: YOUR_API_KEY
```

## Creating API Keys

<Steps>
  <Step title="Navigate to API Keys">
    Access the API Keys section in your dashboard at `/api-keys`.
  </Step>

  <Step title="Create New Key">
    Click "Create API Key" and provide:

    * **Name**: Descriptive name for the key (e.g., "Production Automation")
    * **Description**: Optional details about key usage
    * **Scopes**: Permissions for the key (read/write access)
    * **Expiration**: Optional expiration date

    <Warning>
      The full API key is shown only once during creation. Store it securely.
    </Warning>
  </Step>

  <Step title="Store Securely">
    Save the API key in a secure location:

    * Environment variables
    * Secrets management service (AWS Secrets Manager, Azure Key Vault)
    * Password manager

    Never commit keys to version control or share them publicly.
  </Step>
</Steps>

## Request Format

Include the API key in the `X-API-Key` header of every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.documind.cloud/api/v1/upload \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: multipart/form-data' \
    -F 'files=@document.pdf'
  ```

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

  headers = {
      'X-API-Key': API_KEY
  }

  response = requests.post(
      'https://api.documind.cloud/api/v1/upload',
      headers=headers,
      files={'files': open('document.pdf', 'rb')}
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.documind.cloud/api/v1/upload', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.API_KEY
    },
    body: formData
  });
  ```
</CodeGroup>

## API Key Scopes

Control what operations each API key can perform:

| Scope               | Description                   | Endpoints                                        |
| ------------------- | ----------------------------- | ------------------------------------------------ |
| `extractions:read`  | View extraction results       | `GET /data/extractions`, `GET /pending-reviews`  |
| `extractions:write` | Create and modify extractions | `POST /upload`, `POST /extract`, `PUT /review`   |
| `api_keys:read`     | List API keys                 | `GET /auth/api-keys`                             |
| `api_keys:write`    | Create/update API keys        | `POST /auth/api-keys`, `PUT /auth/api-keys/{id}` |
| `usage:read`        | View usage metrics            | `GET /usage/current`, `GET /usage/credits`       |
| `admin`             | Full access to all resources  | All endpoints                                    |

<Tip>
  For automation scripts, create keys with only the scopes they need: `extractions:read` and `extractions:write`.
</Tip>

## Managing API Keys

### List All Keys

```bash theme={null}
curl https://api.documind.cloud/api/v1/auth/api-keys \
  -H 'X-API-Key: YOUR_API_KEY'
```

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": "key_abc123",
      "name": "Production Bot",
      "prefix": "dk_live_",
      "scopes": ["extractions:read", "extractions:write"],
      "is_active": true,
      "is_revoked": false,
      "created_at": "2024-01-15T10:30:00Z",
      "expires_at": "2025-01-15T10:30:00Z"
    }
  ]
  ```
</ResponseExample>

### Update API Key

Update key properties like name, scopes, or expiration:

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT https://api.documind.cloud/api/v1/auth/api-keys/key_abc123 \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "Updated Production Bot",
      "scopes": ["extractions:read", "extractions:write", "usage:read"],
      "expires_in_days": 365
    }'
  ```
</RequestExample>

### Revoke API Key

Immediately disable an API key:

```bash theme={null}
curl -X DELETE https://api.documind.cloud/api/v1/auth/api-keys/key_abc123 \
  -H 'X-API-Key: YOUR_API_KEY'
```

<Warning>
  Revoked keys cannot be reactivated. You must create a new key.
</Warning>

## Organization-Wide Keys

Create API keys that work across your entire organization:

<RequestExample>
  ```json Request Body theme={null}
  {
    "name": "Org-wide Bot Key",
    "org_wide": true,
    "scopes": ["extractions:read", "extractions:write"],
    "expires_in_days": 90
  }
  ```
</RequestExample>

Organization-wide keys:

* Share credits across the organization
* Access extractions from any team member
* Ideal for shared automation infrastructure

## Error Responses

### 401 Unauthorized

Missing or invalid API key:

```json theme={null}
{
  "detail": "Invalid authentication credentials"
}
```

**Solution**: Verify your API key is correct and included in the `X-API-Key` header.

### 403 Forbidden

API key lacks required scope:

```json theme={null}
{
  "detail": "Insufficient permissions for this operation"
}
```

**Solution**: Update the API key's scopes or use a key with appropriate permissions.

### 402 Payment Required

Insufficient credits:

```json theme={null}
{
  "detail": "Insufficient credits. Please upgrade your plan or wait for your daily credits to refresh."
}
```

**Solution**: Purchase more credits to continue processing.

## Security Best Practices

<AccordionGroup>
  <Accordion title="Environment Variables">
    Store API keys in environment variables, not in code:

    ```bash .env theme={null}
    DOCUMIND_API_KEY=dk_live_abc123xyz
    ```

    ```python theme={null}
    import os
    api_key = os.environ['DOCUMIND_API_KEY']
    ```
  </Accordion>

  <Accordion title="Key Rotation">
    Rotate API keys periodically (every 90 days recommended):

    1. Create a new API key
    2. Update your applications to use the new key
    3. Verify everything works
    4. Revoke the old key
  </Accordion>

  <Accordion title="Least Privilege">
    Grant only the minimum scopes required:

    * **Read-only automation**: `extractions:read` only
    * **Processing automation**: `extractions:read`, `extractions:write`
    * **Admin operations**: All scopes
  </Accordion>

  <Accordion title="Monitoring">
    Track API key usage via the dashboard:

    * API calls per key
    * Last used timestamp
    * Unusual activity patterns
  </Accordion>
</AccordionGroup>

## Next Steps

<Card title="Quick Start Guide" icon="rocket" href="/api/quickstart">
  Make your first authenticated API request
</Card>