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

# Authentication

> Learn how to authenticate with the PeopleContext API

## API Key Authentication

The PeopleContext API uses API keys to authenticate requests. Include your API key in the `Authorization` header as a Bearer token.

<Warning>
  **Keep your API key secure!** Never commit it to version control or expose it in client-side code.
</Warning>

## Making Authenticated Requests

Include your API key in the `Authorization` header:

<CodeGroup>
  ```python Python theme={null}
  import requests

  headers = {
      "Authorization": "Bearer your_api_key_here",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://api.peoplecontext.com/v1/person/enrich",
      headers=headers,
      json={"github": "torvalds", "websets": ["github"]}
  )
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const headers = {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  };

  const response = await axios.post(
    'https://api.peoplecontext.com/v1/person/enrich',
    {
      github: 'torvalds',
      websets: ['github']
    },
    { headers }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.peoplecontext.com/v1/person/enrich" \
    -H "Authorization: Bearer your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{"github": "torvalds", "websets": ["github"]}'
  ```
</CodeGroup>

## Environment Variables

Store your API key in environment variables to keep it secure:

<CodeGroup>
  ```bash .env theme={null}
  PEOPLE_CONTEXT_API_KEY=your_api_key_here
  ```

  ```python Python theme={null}
  import os
  from dotenv import load_dotenv

  load_dotenv()

  API_KEY = os.getenv("PEOPLE_CONTEXT_API_KEY")
  headers = {"Authorization": f"Bearer {API_KEY}"}
  ```

  ```javascript Node.js theme={null}
  require('dotenv').config();

  const API_KEY = process.env.PEOPLE_CONTEXT_API_KEY;
  const headers = { 'Authorization': `Bearer ${API_KEY}` };
  ```
</CodeGroup>

## Error Responses

### 401 Unauthorized

Missing API key:

```json theme={null}
{
  "detail": "Missing API key. Include 'Authorization: Bearer <key>' header."
}
```

Invalid or revoked API key:

```json theme={null}
{
  "detail": "Invalid or revoked API key."
}
```

### 403 Forbidden

Organization is inactive:

```json theme={null}
{
  "detail": "Organization is inactive."
}
```

### 429 Too Many Requests

Rate limit exceeded (1000 requests per minute):

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 42 seconds."
}
```

Monthly quota limit exceeded:

```json theme={null}
{
  "detail": "Monthly request limit exceeded."
}
```

## Rate Limits

<Warning>
  **Rate Limit**: 1,000 requests per minute per API key\
  Exceeding this limit will result in HTTP 429 (Too Many Requests) responses with a `Retry-After` header.
</Warning>

## Quota Tracking

All authenticated API responses include headers to help you monitor your monthly quota usage:

| Header              | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `X-Quota-Used`      | Number of requests used in the current billing period |
| `X-Quota-Limit`     | Total requests allowed in your plan                   |
| `X-Quota-Remaining` | Number of requests remaining                          |

### Example Response Headers

```http theme={null}
HTTP/1.1 200 OK
X-Quota-Used: 2847
X-Quota-Limit: 10000
X-Quota-Remaining: 7153
```

<Tip>
  Use these headers to track your usage programmatically and avoid hitting your monthly quota limit.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion icon="shield-halved" title="Security">
    * Never hardcode API keys in your source code
    * Use environment variables or secret management systems
    * Rotate keys regularly
    * Use different keys for development and production
  </Accordion>

  <Accordion icon="gauge-high" title="Performance">
    * Implement exponential backoff for rate limit errors
    * Cache responses when possible
    * Monitor the rate limit headers
  </Accordion>

  <Accordion icon="triangle-exclamation" title="Error Handling">
    * Always check response status codes
    * Implement retry logic for transient errors (500, 503)
    * Handle rate limits gracefully
  </Accordion>
</AccordionGroup>