> ## 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

Every Forerunner API request needs a Bearer token in the Authorization header. The token identifies your account, scopes every response to your data, and records the request in our audit trail.

## Getting your API key

API keys are issued per account and per environment, so a staging key does not work against production. To obtain one:

<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 account 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. A successful response confirms the key is configured correctly:

```bash cURL theme={null}
curl https://app.withforerunner.com/api/v1/files \
  -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 `Authorization` header | 401 | Send the header on every request, including retries |
| Missing `Bearer` prefix | 401 | Ensure your Authorization header includes `Bearer` before the API key |
| Rotated or deleted API key | 401 | Contact your Customer Success Manager for a new API key |
| Wrong environment | 401 | Verify you're using the correct base URL, and a key issued for that environment |
| Line breaks or tabs in API key | 401 | Remove line breaks and tabs pasted into your API key value |
| HTTP client `User-Agent` blocked by our firewall | 403 | Clear the `User-Agent` header. See [Errors](/docs/developers/v1/errors) for details |

A `401` body is plain text, not the JSON `errors` array the rest of the API returns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.