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

# Authentication

> Authenticate your API requests with Bearer tokens

## Overview

All Forerunner API requests require authentication using Bearer tokens passed in the Authorization header. This ensures secure access to your organization's data and maintains audit trails for API activity.

## Getting your API key

API keys are provided by Forerunner and are organization-specific. To obtain an API key:

<Steps>
  <Step title="Contact your Customer Success Manager">
    Reach out to your Customer Success Manager to request API access.
  </Step>

  <Step title="Or email our team">
    Send a request to [engineering@withforerunner.com](mailto:engineering@withforerunner.com) with your organization name and use case.
  </Step>

  <Step title="Receive your API key">
    You'll receive a long-lived API key that can be used for all API requests.
  </Step>
</Steps>

## Using your API key

Include your API key in the Authorization header of every request:

```bash cURL theme={null}
curl https://app.withforerunner.com/api/v1/properties \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## API key lifecycle

<Warning>
  API keys are **long-lived** but may be rotated for security reasons. Always store API keys securely and be prepared to update your integration if notified of an API key rotation.
</Warning>

### API key security best practices

<AccordionGroup>
  <Accordion title="Store API keys securely">
    * Never commit API keys to version control
    * Use environment variables or secure secret management systems
    * Rotate API keys periodically as a security best practice
  </Accordion>

  <Accordion title="Limit API key exposure">
    * Only share API keys with authorized team members
    * Use separate API keys for different environments when possible
    * Monitor API usage for unexpected patterns
  </Accordion>

  <Accordion title="Handle API key errors gracefully">
    * Implement proper error handling for `401 Unauthorized` responses
    * Log authentication failures for security monitoring
    * Have a process to quickly rotate compromised API keys
  </Accordion>
</AccordionGroup>

## Authentication errors

| Issue                                   | Status Code | Solution                                                                                                                     |
| --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Missing `Bearer` prefix                 | 401         | Ensure your Authorization header includes `Bearer` before the API key                                                        |
| Expired or revoked API key              | 401         | Contact your Customer Success Manager for a new API key                                                                      |
| Wrong environment                       | 401         | Verify you're using the correct base URL (staging vs production)                                                             |
| Whitespace in API key                   | 401         | Trim any extra spaces from your API key value                                                                                |
| HTTP client `User-Agent` blocked by WAF | 403         | Remove or clear the `User-Agent` header in Postman, Insomnia, or similar tools. See [Errors](/developers/errors) for details |

## Testing your authentication

Use this simple request to verify your API key is working:

```bash theme={null}
curl https://app.withforerunner.com/api/v1/properties?page=1 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A successful response indicates your authentication is configured correctly.