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

# Authentication

> Authenticate your API requests using your Screenshotly API key.

All Screenshotly API requests require authentication via an API key.

## Getting your API key

1. Sign in to your [dashboard](https://app.screenshotly.dev)
2. Navigate to [API settings](https://app.screenshotly.dev/settings/api)
3. Copy your API key

## Using your API key

Pass your API key using either the `X-API-Key` header or the `api_key` query parameter.

### Header authentication (recommended)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.screenshotly.dev/v1/capture \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com"}'
  ```

  ```javascript JavaScript SDK theme={null}
  import { Screenshotly } from 'screenshotly-js';

  const client = new Screenshotly('YOUR_API_KEY');
  ```

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

  headers = {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
  }
  ```
</CodeGroup>

### Query parameter authentication

You can also pass the API key as a query parameter:

```bash theme={null}
curl "https://api.screenshotly.dev/v1/capture?api_key=YOUR_API_KEY&url=https://example.com"
```

<Warning>
  Query parameter authentication exposes your API key in URLs and server logs. Use header authentication whenever possible.
</Warning>

## Environment variables

Store your API key in an environment variable to avoid hardcoding it:

```bash theme={null}
export SCREENSHOTLY_API_KEY="your-api-key-here"
```

Then reference it in your code:

<CodeGroup>
  ```javascript Node.js theme={null}
  const client = new Screenshotly(process.env.SCREENSHOTLY_API_KEY);
  ```

  ```python Python theme={null}
  import os
  API_KEY = os.environ['SCREENSHOTLY_API_KEY']
  ```
</CodeGroup>

## Authentication errors

If your API key is missing, the API returns a `401` response:

```json theme={null}
{
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Pass it via X-API-Key header or api_key query parameter."
  }
}
```

If your API key is invalid or has been revoked:

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

## Security best practices

* **Never expose keys in client-side code** — only use API keys in server-side applications
* **Don't commit keys to version control** — use `.env` files and add them to `.gitignore`
* **Use separate keys for environments** — generate different keys for development, staging, and production
* **Rotate keys regularly** — revoke old keys and generate new ones from the dashboard
* **Revoke compromised keys immediately** — if a key is exposed, revoke it in [API settings](https://app.screenshotly.dev/settings/api)