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

# Authentication

> Secure your API requests with API key authentication

WebLinq uses API key authentication to secure all requests. Every API call must include a valid API key to identify your account and track usage.

<Info>
  All endpoints require authentication except health checks. This ensures your usage is tracked and your data remains
  secure.
</Info>

## Get your API key

<Steps>
  <Step title="Create your account">
    [Sign up at WebLinq](https://weblinq.dev/sign-up) - it's free to get started.
  </Step>

  <Step title="Generate your key">
    1. Go to [API Keys](https://weblinq.dev/dashboard/api-keys) in your dashboard 2. Click "Create API Key" and give it a
       descriptive name 3. Copy your API key immediately
       <Warning>API keys are only shown once. Store them securely in environment variables.</Warning>
  </Step>

  <Step title="Test your key">
    Verify your API key works:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -H "Authorization: Bearer YOUR_API_KEY" \
        "https://api.weblinq.dev/v1/user/me"
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch('https://api.weblinq.dev/v1/user/me', {
        headers: {
          Authorization: 'Bearer YOUR_API_KEY',
        },
      });

      const data = await response.json();
      console.log(data.success ? 'Authenticated!' : 'Failed');
      ```

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

      response = requests.get(
          'https://api.weblinq.dev/v1/user/me',
          headers={'Authorization': 'Bearer YOUR_API_KEY'}
      )

      print('Authenticated!' if response.ok else 'Failed')
      ```
    </CodeGroup>
  </Step>
</Steps>

## Authentication methods

### Bearer token

Include your API key in the `Authorization` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.weblinq.dev/v1/web/markdown" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.weblinq.dev/v1/web/markdown', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: 'https://example.com' }),
  });
  ```

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

  response = requests.post(
      'https://api.weblinq.dev/v1/web/markdown',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={'url': 'https://example.com'}
  )
  ```
</CodeGroup>

<Tip>Use `Authorization: Bearer` when possible - it's the standard approach and works with most HTTP libraries.</Tip>

## Error responses

<ResponseExample>
  ```json Unauthorized (401) theme={null}
  {
    "success": false,
    "error": {
      "code": "AUTHENTICATION_REQUIRED",
      "message": "Authentication required",
      "requestId": "req_1234567890abcdef"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Rate Limited (429) theme={null}
  {
    "success": false,
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded",
      "requestId": "req_1234567890abcdef"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

## Rate limits

API keys have different limits based on your plan:

| Plan           | Requests/Hour | Concurrent | Features          |
| -------------- | ------------- | ---------- | ----------------- |
| **Free**       | 1,000         | 5          | All endpoints     |
| **Pro**        | 10,000        | 20         | Priority support  |
| **Enterprise** | Custom        | Custom     | Dedicated support |

### Rate limit headers

Every response includes rate limit information:

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705312200
```

## Security best practices

### Environment variables

Always store API keys in environment variables:

<Tabs>
  <Tab title="Node.js">
    ```bash theme={null}
    # .env file
    WEBLINQ_API_KEY=your_api_key_here
    ```

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

  <Tab title="Python">
    ```bash theme={null}
    export WEBLINQ_API_KEY=your_api_key_here
    ```

    ```python theme={null}
    import os
    api_key = os.getenv('WEBLINQ_API_KEY')
    ```
  </Tab>

  <Tab title="Docker">
    ```dockerfile theme={null}
    # Pass as environment variable
    docker run -e WEBLINQ_API_KEY=your_api_key_here your-app
    ```
  </Tab>
</Tabs>

### Security checklist

<AccordionGroup>
  <Accordion title="Key management" icon="key">
    * Create separate keys for development and production
    * Rotate keys every 90 days
    * Use descriptive names to track key usage
    * Delete unused keys immediately
  </Accordion>

  <Accordion title="Storage security" icon="shield">
    * Store keys in environment variables or secrets managers - Never commit keys to version control - Don't embed keys in
      client-side code - Avoid using keys in URLs or query parameters
  </Accordion>

  <Accordion title="Usage monitoring" icon="chart-line">
    * Monitor API usage in your dashboard
    * Set up alerts for unusual activity
    * Review key usage patterns regularly
    * Track failed authentication attempts
  </Accordion>
</AccordionGroup>

<Warning>**Security reminder:** Never share API keys, commit them to Git, or use them in client-side code.</Warning>

## Need help?

<CardGroup cols={2}>
  <Card title="Get Support" icon="envelope" href="mailto:support@weblinq.dev">
    Email us for technical support
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Explore all available endpoints
  </Card>
</CardGroup>