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

# Authentication

> How to authenticate your API requests

## API Key Authentication

All API requests require authentication using an API key. Include your key in the `x-api-key` header:

```bash theme={null}
x-api-key: YOUR_API_KEY
```

## Getting Your API Key

1. Log in to your dashboard at [YOUR\_DEPLOYMENT.lupitor.com](https://YOUR_DEPLOYMENT.lupitor.com)
2. Navigate to **API Keys** in your company settings
3. Click **Create API Key**
4. Choose a scope and give it a descriptive name
5. Copy your key immediately (it won't be shown again!)

<Warning>
  Never share your API keys or commit them to version control. Treat them like passwords.
</Warning>

## API Key Scopes

API keys have different permission levels:

<CardGroup cols={2}>
  <Card title="Read" icon="eye">
    **Read-only access**

    * List leads
    * View conversations
    * Get analytics
  </Card>

  <Card title="Write" icon="pen">
    **Full access**

    * Create leads
    * Update campaigns
    * All read operations
  </Card>
</CardGroup>

<Tip>
  **Write** scope automatically includes **Read** access. You don't need separate keys.
</Tip>

## Campaign Scoping

API keys can be scoped to specific campaigns or have company-wide access:

### Company-Wide Access

```json theme={null}
{
  "scope": "write",
  "campaignId": null  // Access all campaigns
}
```

### Campaign-Specific Access

```json theme={null}
{
  "scope": "write",
  "campaignId": "k978..."  // Only this campaign
}
```

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=k978... \
    -H "x-api-key: sk_test_abc123xyz"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=k978...',
    {
      headers: {
        'x-api-key': 'sk_test_abc123xyz'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads',
      params={'campaignId': 'k978...'},
      headers={'x-api-key': 'sk_test_abc123xyz'}
  )
  ```
</CodeGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion icon="lock" title="Store Securely">
    * Use environment variables
    * Never hardcode in source code
    * Use secret management tools (e.g., AWS Secrets Manager, 1Password)
  </Accordion>

  <Accordion icon="rotate" title="Rotate Regularly">
    * Rotate keys periodically
    * Immediately revoke compromised keys
    * Create new keys before deleting old ones
  </Accordion>

  <Accordion icon="shield" title="Limit Scope">
    * Use read-only keys where possible
    * Scope to specific campaigns when appropriate
    * Create separate keys for different environments
  </Accordion>

  <Accordion icon="clock" title="Monitor Usage">
    * Review API logs regularly
    * Set up alerts for unusual activity
    * Track which keys are being used
  </Accordion>
</AccordionGroup>

## Error Responses

### Missing API Key

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Missing API key"
}
```

**HTTP Status:** `401 Unauthorized`

### Invalid API Key

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Invalid or inactive API key"
}
```

**HTTP Status:** `401 Unauthorized`

### Insufficient Permissions

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Insufficient permissions"
}
```

**HTTP Status:** `403 Forbidden`

## Need Help?

If you're having authentication issues:

* Verify your API key is correct
* Check that the key hasn't been revoked
* Ensure you're using the correct scope
* Contact support at [support@lupitor.com](mailto:support@lupitor.com)