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

# Authentication

> Authenticate with the Topify.ai public API using API keys.

The public API uses API key authentication. Every request must include your key in the `X-API-Key` header.

## Request header

```
X-API-Key: tk_live_<your-key>
```

## Getting an API key

Generate API keys from your Topify.ai dashboard under **Management > Members**, or programmatically via the [agentic setup](/api-reference/agentic-setup) endpoints. Each key is scoped to your team and gives access to all projects owned by that team. Only team admins can create API keys.

Project-scoped API keys are not currently issued. Treat each API key as an administrator credential for the full team and store it accordingly.

<Danger>
  API keys are for trusted server-side use only. Never embed one in browser JavaScript, mobile or desktop client code, public repositories, logs, AI prompts, or chat history. Load it from a secret manager or protected environment variable and rotate it immediately if exposed.
</Danger>

<Note>
  The full API key is shown only once when it is created. Store it immediately in a secret manager. The Members page displays only the key prefix; if the full value is lost, create a replacement key and disable the old one.
</Note>

## Rate limiting

Requests are rate-limited per API key. Limits depend on your plan tier:

| Tier     | Requests per minute | Burst allowance | Total per window |
| -------- | ------------------- | --------------- | ---------------- |
| Standard | 60                  | 10              | 70               |
| Premium  | 300                 | 50              | 350              |

### Response headers

Every response includes rate limit information:

| Header                  | Type    | Description                                             |
| ----------------------- | ------- | ------------------------------------------------------- |
| `X-RateLimit-Limit`     | integer | Maximum requests allowed in the current window          |
| `X-RateLimit-Remaining` | integer | Requests remaining before throttling                    |
| `Retry-After`           | integer | Seconds until the window resets (only present on `429`) |

### Rate limit exceeded

When you exceed the limit, the API returns HTTP `429`:

```json theme={null}
{
  "detail": "Rate limit exceeded. Retry after 42 seconds."
}
```

## Key lifecycle

| State        | Behavior                                          |
| ------------ | ------------------------------------------------- |
| **Active**   | Key is valid and accepts requests                 |
| **Inactive** | Key has been disabled by an admin. Returns `401`  |
| **Expired**  | Key has passed its expiration date. Returns `401` |

You can deactivate or delete keys at any time from the dashboard.

## Example requests

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://topify-customer-api-production.up.railway.app/api/public/v1/projects" \
      -H "X-API-Key: ${TOPIFY_API_KEY}"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import httpx

    client = httpx.Client(
        base_url="https://topify-customer-api-production.up.railway.app/api/public/v1",
        headers={"X-API-Key": os.environ["TOPIFY_API_KEY"]},
    )

    resp = client.get("/projects")
    print(resp.json())
    ```
  </Tab>

  <Tab title="Node.js (server-side)">
    ```javascript theme={null}
    const BASE_URL = "https://topify-customer-api-production.up.railway.app/api/public/v1";
    const API_KEY = process.env.TOPIFY_API_KEY;
    if (!API_KEY) throw new Error("TOPIFY_API_KEY is not set");

    const resp = await fetch(`${BASE_URL}/projects`, {
      headers: { "X-API-Key": API_KEY },
    });
    const data = await resp.json();
    console.log(data);
    ```
  </Tab>
</Tabs>

## Error responses

| Status | Detail                                        | Cause                                     |
| ------ | --------------------------------------------- | ----------------------------------------- |
| `401`  | `Missing X-API-Key header`                    | No `X-API-Key` header provided            |
| `401`  | `Invalid API key`                             | Key is not recognized                     |
| `401`  | `API key is inactive`                         | Key was disabled by an admin              |
| `401`  | `API key has expired`                         | Key passed its configured expiration date |
| `429`  | `Rate limit exceeded. Retry after N seconds.` | Too many requests in the current window   |