> ## Documentation Index
> Fetch the complete documentation index at: https://orwel-22af1265.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate your API requests

## API Keys

Orwel uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure!

### Key Types

Orwel provides two types of API keys per workspace:

<CardGroup cols={2}>
  <Card title="Production Keys" icon="shield-check">
    Use in production environments

    * 1000 requests per minute
    * Full access to workspace data
    * Tracked separately for monitoring
  </Card>

  <Card title="Development Keys" icon="flask">
    Use for testing and development

    * 100 requests per minute
    * Full access to workspace data
    * Safe for local development
  </Card>
</CardGroup>

## Authentication Methods

You can authenticate requests using either of these methods:

### Bearer Token (Recommended)

Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.orwel.io/api/v1/leads" \
    -H "Authorization: Bearer orw_prod_abc123..."
  ```

  ```javascript JavaScript theme={null}
  fetch('https://api.orwel.io/api/v1/leads', {
    headers: {
      'Authorization': 'Bearer orw_prod_abc123...'
    }
  })
  ```

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

  headers = {
      'Authorization': 'Bearer orw_prod_abc123...'
  }

  requests.get('https://api.orwel.io/api/v1/leads', headers=headers)
  ```
</CodeGroup>

### Custom Header

Alternatively, use the `x-api-key` header:

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.orwel.io/api/v1/leads" \
    -H "x-api-key: orw_prod_abc123..."
  ```

  ```javascript JavaScript theme={null}
  fetch('https://api.orwel.io/api/v1/leads', {
    headers: {
      'x-api-key': 'orw_prod_abc123...'
    }
  })
  ```
</CodeGroup>

## Managing API Keys

### Generating Keys

<Steps>
  <Step title="Access Settings">
    Navigate to your workspace settings in the Orwel dashboard
  </Step>

  <Step title="Go to API Keys">
    Click on the "API Keys" section
  </Step>

  <Step title="Generate New Key">
    Choose between Production or Development key
  </Step>

  <Step title="Copy and Store">
    Copy the key immediately - it won't be shown again
  </Step>
</Steps>

### Key Rotation

We recommend rotating your API keys regularly:

<Warning>
  When you rotate a key, the old key is immediately invalidated. Update all applications using the old key before rotating.
</Warning>

1. Generate a new API key
2. Update all applications to use the new key
3. Monitor for any failed requests
4. Delete the old key once migration is complete

## Security Best Practices

<AccordionGroup>
  <Accordion icon="lock" title="Never Expose Keys in Client-Side Code">
    API keys should only be used in server-side code. Never include them in:

    * Frontend JavaScript
    * Mobile app code
    * Public repositories
    * Client-side configuration files
  </Accordion>

  <Accordion icon="key" title="Use Environment Variables">
    Store API keys in environment variables, not in your code:

    ```bash theme={null}
    # .env
    ORWEL_API_KEY=orw_prod_abc123...
    ```

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

  <Accordion icon="rotate" title="Rotate Keys Regularly">
    Rotate your API keys every 90 days or immediately if you suspect a key has been compromised.
  </Accordion>

  <Accordion icon="eye" title="Monitor Key Usage">
    Regularly review your API key usage in the dashboard. Look for:

    * Unexpected traffic patterns
    * Failed authentication attempts
    * Unusual geographic locations
  </Accordion>
</AccordionGroup>

## Key Tracking

Every API key tracks its last usage:

* **Production Key**: `prod_last_use` timestamp
* **Development Key**: `dev_last_use` timestamp

You can view this information in your workspace settings to monitor key activity.

## Authentication Errors

### 401 Unauthorized

Returned when the API key is invalid or missing:

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

**Common causes:**

* Missing `Authorization` or `x-api-key` header
* Invalid or expired API key
* Typo in the API key

### 403 Forbidden

Returned when you don't have access to the requested resource:

```json theme={null}
{
  "error": "forbidden",
  "message": "Access denied to requested resource"
}
```

**Common causes:**

* Trying to access another workspace's data
* Resource doesn't exist in your workspace

## Testing Authentication

Test your API key with this simple request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.orwel.io/api/v1/users" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const testAuth = async () => {
    const response = await fetch('https://api.orwel.io/api/v1/users', {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    if (response.ok) {
      console.log('✅ Authentication successful');
    } else {
      console.log('❌ Authentication failed');
    }
  };
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Rate Limiting" icon="gauge" href="/concepts/rate-limiting">
    Learn about rate limits for your API keys
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Start making API calls
  </Card>
</CardGroup>