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

# Authentication

> Learn how to authenticate API requests using scoped API keys with the X-API-Key header

# Authentication

All API requests require authentication via an API key. Keys are scoped to your organization and can be created in the dashboard.

## Sending your API key

Include your key in one of these headers (in order of preference):

<CodeGroup>
  ```bash X-API-Key (preferred) theme={null}
  curl https://api.dronelist.io/v1/equipment \
    -H "X-API-Key: dl_your_key_here"
  ```

  ```bash Authorization Bearer (fallback) theme={null}
  curl https://api.dronelist.io/v1/equipment \
    -H "Authorization: Bearer dl_your_key_here"
  ```
</CodeGroup>

## API key format

All keys use the `dl_` prefix followed by a random string:

```
dl_a1b2c3d4e5f6g7h8i9j0...
```

<Warning>
  API keys are shown only once when created. Store them securely — you cannot retrieve the key value after creation.
</Warning>

## Scopes

Each API key has one or more scopes that control what it can access:

| Scope            | Grants access to                                                              |
| ---------------- | ----------------------------------------------------------------------------- |
| `equipment:read` | `GET /v1/equipment`, `GET /v1/equipment/:id`, `GET /v1/equipment/:id/flights` |
| `project:read`   | `GET /v1/projects`, `GET /v1/projects/:id`                                    |
| `service:read`   | `GET /v1/services`, `GET /v1/services/:id`                                    |

A request to an endpoint outside the key's scopes returns a `403 Forbidden` error.

## Creating API keys

1. Go to [Settings > API Keys](https://app.dronelist.io/settings/api-keys)
2. Click **Create API Key**
3. Name the key (e.g., "Production integration")
4. Select the scopes you need
5. Optionally set an expiration date
6. Copy the generated key immediately

## Security best practices

<AccordionGroup>
  <Accordion title="Use the minimum scopes needed">
    Only grant the scopes your integration actually requires. You can always create additional keys with different scopes for different services.
  </Accordion>

  <Accordion title="Set expiration dates">
    For temporary integrations or testing, set an expiration date. Expired keys automatically stop working.
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Create a new key, update your integration, then revoke the old one. This limits exposure if a key is compromised.
  </Accordion>

  <Accordion title="Never expose keys in client-side code">
    API keys should only be used in server-side code. Never include them in browser JavaScript, mobile apps, or public repositories.
  </Accordion>
</AccordionGroup>

## Error responses

| Status             | Meaning                                   |
| ------------------ | ----------------------------------------- |
| `401 Unauthorized` | Missing or invalid API key                |
| `403 Forbidden`    | Key is valid but lacks the required scope |