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

# Authentication

> Learn how to authenticate with the Fifteenth Partner API

## Overview

The Fifteenth Partner API uses Bearer token authentication with API keys. All requests must include a valid API key in the Authorization header to access protected endpoints.

## Getting Started

<Steps>
  <Step title="Contact Partner Success">
    Email [partners@fifteenth.com](mailto:partners@fifteenth.com) to request API access. Include:

    * Your company name and website
    * Estimated client volume
    * Integration timeline
  </Step>

  <Step title="Complete Onboarding">
    Our partner success team will guide you through:

    * Partnership agreement execution
    * Technical requirements review
  </Step>

  <Step title="Receive API Keys">
    Once onboarded, you'll receive:

    * Production API key for live integration
  </Step>
</Steps>

## API Key Authentication

### Using Your API Key

Include your API key in the Authorization header of all requests:

```http theme={null}
Authorization: Bearer your_api_key_here
```

### API Key Format

Fifteenth API keys follow this format:

```
15th_<random_string>

Example:
15th_M4pQ7vN9xR2mK5wL8S1E6B
```

### Production Environment

<Card title="Production" icon="shield-check">
  **Purpose**: Live client operations

  **Environment**: Production with real client data

  **Rate Limits**: 100 requests/minute, 10,000/day
</Card>

## Request Examples

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

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

  response = requests.get(
      "https://api.fifteenth.com/v1beta/accounts",
      headers=headers
  )

  if response.status_code == 200:
      accounts = response.json()
      print(f"Found {len(accounts)} accounts")
  else:
      print(f"Error: {response.status_code}")
  ```

  ```javascript JavaScript theme={null}
  const headers = {
      'Authorization': 'Bearer 15th_your_api_key_here',
      'Content-Type': 'application/json'
  };

  const response = await fetch('https://api.fifteenth.com/v1beta/accounts', {
      method: 'GET',
      headers: headers
  });

  if (response.ok) {
      const accounts = await response.json();
      console.log(`Found ${accounts.length} accounts`);
  } else {
      console.log(`Error: ${response.status}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.fifteenth.com/v1beta/accounts" \
    -H "Authorization: Bearer 15th_your_api_key_here" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

## Rate Limits

The API enforces rate limits to ensure fair usage:

* **Production**: 100 requests per minute, 10,000 per day

When you exceed rate limits, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "details": {
      "limit": 100,
      "window_seconds": 60,
      "reset_at": "2024-01-15T10:31:00Z"
    }
  }
}
```

## Security Best Practices

### API Key Security

* **Store Securely**: Never commit API keys to version control
* **Use Environment Variables**: Store keys in environment variables or secure configuration
* **Monitor Usage**: Watch for unusual activity in your API usage

### Implementation Example

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

# Good: Use environment variables
api_key = os.environ.get('FIFTEENTH_API_KEY')
if not api_key:
    raise ValueError("FIFTEENTH_API_KEY environment variable not set")

headers = {"Authorization": f"Bearer {api_key}"}
```

## Error Handling

### Authentication Errors

| Status Code | Error Code                 | Description                     | Solution                      |
| ----------- | -------------------------- | ------------------------------- | ----------------------------- |
| `401`       | `INVALID_API_KEY`          | API key is invalid or malformed | Check your API key format     |
| `401`       | `EXPIRED_API_KEY`          | API key has expired             | Contact support for a new key |
| `403`       | `INSUFFICIENT_PERMISSIONS` | Key lacks required permissions  | Verify your integration scope |
| `429`       | `RATE_LIMIT_EXCEEDED`      | Too many requests               | Wait and retry with backoff   |

### Example Error Response

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "details": {
      "hint": "Ensure your API key starts with '15th_'"
    }
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Make your first API call and create a client account
  </Card>

  <Card title="Create Account" icon="user-plus" href="/endpoints/accounts/create">
    Start by creating your first client account
  </Card>

  <Card title="Upload Documents" icon="file-arrow-up" href="/endpoints/documents/upload">
    Learn how to upload tax documents
  </Card>

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