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

# Authentication

> Learn how to authenticate your API requests

## API Keys

The demeterrr API uses API keys for authentication. API keys identify your organization and determine what resources you can access based on assigned scopes.

<Warning>
  **Keep your API keys secure!** Treat them like passwords. Never expose them in client-side code, public repositories, or logs.
</Warning>

## Creating an API Key

1. Log in to your [demeterrr dashboard](https://app.demeterrr.com)
2. Navigate to **Settings** → **API Keys**
3. Click **Create API Key**
4. Assign a name and select scopes
5. Copy the key immediately (it won't be shown again)

## API Key Format

All demeterrr API keys follow this format:

```
dem_[43 random characters]
```

Example: `dem_xK3p9vL2mN8qR4tY6wZ1aC5eF7gH9jK0lM2nO4pQ6rS8t`

## Making Authenticated Requests

Include your API key in the `X-API-Key` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://app.demeterrr.com/api/v1/contacts \
    -H "X-API-Key: dem_your_api_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://app.demeterrr.com/api/v1/contacts', {
    headers: {
      'X-API-Key': 'dem_your_api_key_here',
      'Content-Type': 'application/json'
    }
  });
  ```

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

  headers = {
      'X-API-Key': 'dem_your_api_key_here',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      'https://app.demeterrr.com/api/v1/contacts',
      headers=headers
  )
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://app.demeterrr.com/api/v1/contacts');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: dem_your_api_key_here',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  curl_close($ch);
  ```
</CodeGroup>

## Alternative: Bearer Token

You can also use the `Authorization` header with a Bearer token:

```bash theme={null}
curl https://app.demeterrr.com/api/v1/contacts \
  -H "Authorization: Bearer dem_your_api_key_here"
```

## Authentication Errors

### Missing API Key

**Status:** `401 Unauthorized`

```json theme={null}
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Provide via X-API-Key header or Authorization: Bearer <key>"
  }
}
```

### Invalid API Key Format

**Status:** `401 Unauthorized`

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY_FORMAT",
    "message": "Invalid API key format. Key must start with 'dem_'"
  }
}
```

### Invalid or Inactive Key

**Status:** `401 Unauthorized`

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or inactive API key"
  }
}
```

### Expired API Key

**Status:** `401 Unauthorized`

```json theme={null}
{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}
```

## Key Management Best Practices

<AccordionGroup>
  <Accordion title="Rotate keys regularly">
    Create new API keys periodically and delete old ones to minimize security risks.
  </Accordion>

  <Accordion title="Use environment variables">
    Store API keys in environment variables, not in your source code.

    ```bash theme={null}
    export DEMETERRR_API_KEY="dem_your_key_here"
    ```
  </Accordion>

  <Accordion title="Use minimal scopes">
    Only grant the scopes (permissions) your integration actually needs. See [Scopes](/scopes) for details.
  </Accordion>

  <Accordion title="Monitor usage">
    Check your API key usage in the dashboard to detect unusual activity.
  </Accordion>

  <Accordion title="Revoke compromised keys immediately">
    If you suspect a key has been exposed, delete it immediately from your dashboard.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Scopes" icon="shield" href="/scopes">
    Learn about API key permissions
  </Card>

  <Card title="Quick Start" icon="rocket" href="/guides/quickstart">
    Make your first API call
  </Card>
</CardGroup>