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

# Authentication

> Learn how to authenticate your Crawleo API requests, manage API keys securely, and handle authentication errors.

## API Key Authentication

All Crawleo API requests require authentication using your API key.

### Getting Your API Key

<Steps>
  <Step title="Create an Account">
    Sign up at [crawleo.dev/login](https://www.crawleo.dev/login).
  </Step>

  <Step title="Choose a Plan">
    Subscribe to a plan at [crawleo.dev/pricing](https://www.crawleo.dev/pricing).
  </Step>

  <Step title="Copy Your Key">
    Access your API key from the [dashboard](https://www.crawleo.dev/dashboard).
  </Step>
</Steps>

### Using Your API Key

Include your API key in one of the following headers — both methods are equivalent:

| Method           | Header          | Format                |
| ---------------- | --------------- | --------------------- |
| **Bearer Token** | `Authorization` | `Bearer YOUR_API_KEY` |
| **X-API-Key**    | `x-api-key`     | `YOUR_API_KEY`        |

### Example Requests

<CodeGroup>
  ```bash cURL (Authorization Header) theme={null}
  curl -X GET "https://api.crawleo.dev/search?query=hello" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (x-api-key Header) theme={null}
  curl -X GET "https://api.crawleo.dev/search?query=hello" \
    -H "x-api-key: YOUR_API_KEY"
  ```

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

  response = requests.get(
      "https://api.crawleo.dev/search",
      params={"query": "hello"},
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )

  data = response.json()
  print(data)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.crawleo.dev/search?query=hello",
    {
      headers: {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Security Best Practices

<Warning>
  Never expose your API key in client-side code or public repositories.
</Warning>

<AccordionGroup>
  <Accordion title="Use Environment Variables" icon="lock">
    Store your API key in environment variables rather than hardcoding it:

    ```bash theme={null}
    export CRAWLEO_API_KEY="your_api_key_here"
    ```

    ```python theme={null}
    import os
    api_key = os.environ.get("CRAWLEO_API_KEY")
    ```

    ```javascript theme={null}
    const apiKey = process.env.CRAWLEO_API_KEY;
    ```
  </Accordion>

  <Accordion title="Server-Side Only" icon="server">
    Make API calls from your backend server, not from browser-based JavaScript. Client-side requests would expose your API key to anyone inspecting the page source.
  </Accordion>

  <Accordion title="Rotate Keys Regularly" icon="arrows-rotate">
    Periodically rotate your API keys, especially if you suspect they may have been compromised. You can regenerate keys from the [dashboard](https://www.crawleo.dev/dashboard).
  </Accordion>
</AccordionGroup>

## Error Responses

When authentication fails, you'll receive one of these error responses:

| Status Code | Description       | Cause                                         |
| ----------- | ----------------- | --------------------------------------------- |
| `401`       | Unauthorized      | Invalid or missing API key                    |
| `403`       | Forbidden         | API key doesn't have access to this resource  |
| `429`       | Too Many Requests | Credits exhausted or concurrent limit reached |

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}
```

<CardGroup cols={2}>
  <Card title="Credits & Pricing" icon="coins" href="/credits-pricing">
    Learn about credit costs, plans, and rate limits.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    See the full API documentation.
  </Card>
</CardGroup>