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

# Authentication

> Authenticate requests with a workspace API key. Scope, header format, and rotation.

The Public API uses **workspace API keys**. Each key is bound to a single workspace, and every endpoint runs in that workspace's context.

## Creating a key

1. Sign in to Studio and open the workspace you want to authenticate as.
2. Open **Settings → API keys**.
3. Click **Create API key**. Give it a descriptive name (e.g. `production CLI`, `Zapier integration`).
4. Copy the key starting with `gsk_…` — **you can't see it again** after closing the dialog. Store it in a secrets manager.

<Warning>
  API keys grant full access to the workspace they belong to. Treat them like passwords: never commit them to git, never paste them into Slack or shared docs.
</Warning>

## Sending the key

Both forms are accepted. Pick one per project and stick with it.

<CodeGroup>
  ```bash X-Api-Key header (recommended) theme={null}
  curl https://api.gennia.ai/public/api/v1/agents \
    -H "X-Api-Key: gsk_your_key_here"
  ```

  ```bash Authorization Bearer theme={null}
  curl https://api.gennia.ai/public/api/v1/agents \
    -H "Authorization: Bearer gsk_your_key_here"
  ```
</CodeGroup>

## Errors

| Status | Body code                | Meaning                                                     |
| ------ | ------------------------ | ----------------------------------------------------------- |
| `401`  | `MISSING_API_KEY`        | No `X-Api-Key` header and no `Authorization: Bearer …`.     |
| `401`  | `INVALID_API_KEY_FORMAT` | Key doesn't start with `gsk_` or has wrong length.          |
| `401`  | `INVALID_API_KEY`        | Key is unknown, revoked, or belongs to a deleted workspace. |

A `401` response always means **stop and check the key** — retrying won't help.

## Rotation

Keys don't expire. To rotate:

1. Create a new key in Studio.
2. Roll the new key into your integration (env var, secrets manager).
3. Once you've confirmed the new key works, **revoke** the old one in Studio.

There is no overlap window — both keys work simultaneously until you revoke. Plan rotations during low-traffic windows so you can confirm before pulling the trigger.

## Scope

A key grants **full workspace access**. There is no per-endpoint or per-resource scoping. If you need a reduced surface, run that integration as a separate workspace with its own data and its own key.