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

# Authentication

> How to authenticate API requests

# Authentication

All PromoStack API requests require authentication using an API key.

## Getting Your API Key

1. Log in to [PromoStack Dashboard](https://www.promostack.app/dashboard)
2. Navigate to your app settings
3. Copy your API key from the "API Keys" section

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

## Using Your API Key

Include your API key in the `x-api-key` header of every request:

```bash theme={null}
curl -X POST https://api.promostack.app/referrer \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"uid": "user_123"}'
```

That's it! No additional authentication headers needed. The API Gateway will handle the rest.

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store Keys Securely">
    Use environment variables or secure key management systems. Never hardcode keys in your app.

    ```swift theme={null}
    // iOS - Use Info.plist or Keychain
    let apiKey = Bundle.main.object(forInfoDictionaryKey: "PROMOSTACK_API_KEY")
    ```

    ```kotlin theme={null}
    // Android - Use BuildConfig or encrypted SharedPreferences
    val apiKey = BuildConfig.PROMOSTACK_API_KEY
    ```
  </Accordion>

  <Accordion title="Rotate Keys Regularly">
    Generate new API keys periodically and update your app. Old keys can be revoked in the dashboard.
  </Accordion>

  <Accordion title="Monitor Usage">
    Track API usage in the dashboard to detect unusual patterns or potential key leaks.
  </Accordion>
</AccordionGroup>

## Error Responses

### 401 Unauthorized

Missing or invalid API key:

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

### 403 Forbidden

Valid key but insufficient permissions:

```json theme={null}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have access to this resource"
  }
}
```

## API Key Scopes

All API keys have full access to:

* Referrer endpoints (`/referrer`, `/referrer-claim`)
* Referee endpoints (`/referee-redeem`)
* Webhook endpoints (read-only)

<Note>
  Custom scopes and read-only keys are available on Pro and Enterprise plans.
</Note>