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

# Authentication

> Create Introw API keys, choose scopes, and authenticate requests with x-api-key.

The Introw API uses customer API keys. Each key belongs to one Introw organisation and can only access data in that organisation.

## Create an API key

1. In Introw, go to **Settings > Developer > API keys**.
2. Click **Create API key**.
3. Enter a descriptive name, such as `Production data sync`.
4. Select the scopes your integration needs.
5. Click **Create** and copy the API key.

Store the key immediately. Introw only shows the full key once.

## Authenticate a request

Send the API key in the `x-api-key` header.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.introw.io/api/v1/partners" \
  -H "x-api-key: $INTROW_API_KEY"
```

Do not send API keys as query parameters. Do not expose API keys in frontend code, browser extensions, public repositories, logs, or analytics tools.

## Scopes

Scopes limit what an API key can do. Give each key the smallest set of scopes required for the integration.

| Scope                   | Allows                                                                |
| ----------------------- | --------------------------------------------------------------------- |
| `partners:read`         | List partners and fetch a single partner.                             |
| `partners:write`        | Create partners and update existing partners.                         |
| `commissions:read`      | List and fetch commission payouts and commission lines.               |
| `commissions:write`     | Update payouts and create, edit, decline, or detach commission lines. |
| `affiliate:write`       | Record affiliate conversions server-to-server.                        |
| `portal-sessions:write` | Create authenticated partner portal session links.                    |

If a request uses a valid API key but the key does not include the required scope, the API returns `403 Forbidden`.

## Organisation scoping

API keys are tied to the Introw organisation where they are created. You do not need to send an organisation ID in requests. Introw resolves the organisation from the authenticated API key and applies that boundary to every endpoint.

## Rotate an API key

Rotate API keys on a regular schedule and whenever a key may have been exposed.

1. Create a new API key with the same scopes.
2. Deploy the new key to your integration.
3. Verify the integration is using the new key.
4. Revoke the old key in **Settings > Developer > API keys**.

## Revoke an API key

Revoke a key when an integration is decommissioned, an owner leaves, or a key is suspected to be compromised. Revoked keys stop authenticating immediately.

## Troubleshooting

| Symptom                           | What to check                                                    |
| --------------------------------- | ---------------------------------------------------------------- |
| `401 Unauthorized`                | The `x-api-key` header is missing, invalid, expired, or revoked. |
| `403 Forbidden`                   | The API key is valid but does not include the endpoint's scope.  |
| Requests return the wrong data    | Confirm the key was created in the expected Introw organisation. |
| The full key is no longer visible | Create a replacement key and revoke the old one if needed.       |