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

# Authentication

> Authenticate requests using your 9Pic API key

## Overview

All 9Pic API requests are authenticated with a long-lived API key sent in the `X-API-Key` header. Keys are scoped to one organisation and validated on every request, along with the calling host and the URL's `org_id` / `event_id`.

## Sending the API Key

Add the `X-API-Key` header to every request:

```
X-API-Key: <your_9pic_api_key>
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -i \
    -H "X-API-Key: <your_9pic_api_key>" \
    "https://api.9pic.ai/api/v1/ext/903/event/456/ping"
  ```

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

  response = requests.get(
      "https://api.9pic.ai/api/v1/ext/903/event/456/ping",
      headers={"X-API-Key": "<your_9pic_api_key>"},
  )
  print(response.status_code, response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.9pic.ai/api/v1/ext/903/event/456/ping",
    { headers: { "X-API-Key": "<your_9pic_api_key>" } }
  );
  console.log(response.status, await response.json());
  ```
</CodeGroup>

## Creating an API Key

<Steps>
  <Step title="Open Developer Zone">
    Sign in to [admin.9pic.ai](https://admin.9pic.ai/) and open the **Developer Zone** page from the left sidebar.
  </Step>

  <Step title="Create a new token">
    Click **Create Token**, then confirm in the dialog. The new key is generated server-side and added to your token list.
  </Step>

  <Step title="Copy your token">
    The full key is displayed only once. Click **Copy** and store it in your secret manager. If you lose it, you must delete the old token and create a new one.
  </Step>
</Steps>

<Warning>
  The full API key is shown **only once** at creation time. There is no recovery flow.
</Warning>

<Note>
  Each organisation can have up to **10 API tokens**. You can deactivate or delete tokens at any time from the Developer Zone page.
</Note>

## Managing Tokens

From the **Developer Zone** page you can:

* **Activate / Deactivate** a token using the toggle. Deactivated tokens are immediately rejected.
* **Delete** a token permanently. Any service using that token loses access on the next request.

## What Gets Validated

Every API call is checked against three things:

| Check           | What it enforces                                                                 |
| --------------- | -------------------------------------------------------------------------------- |
| API key         | The `X-API-Key` header is present, the token exists, and the token is active.    |
| Org ownership   | The `org_id` in the URL belongs to the organisation that owns the token.         |
| Event ownership | For event-scoped routes, the `event_id` in the URL belongs to that organisation. |
| Host            | The calling host is on the production allowlist (currently `api.9pic.ai`).       |

A failure on any of these returns a `403`. See [Errors](/api-reference/errors#403-forbidden) for the full list of `403` causes.

## Error Responses

| Status | Meaning                                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------------------- |
| `401`  | The `X-API-Key` header is missing.                                                                         |
| `403`  | The token is invalid, inactive, the URL identifiers do not belong to the org, or the host is not approved. |

See [Errors](/api-reference/errors) for canonical descriptions and retry guidance.