> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/api-keys.md).

# API keys and permissions

API keys let your code, the [SDK](https://docs.avastudio.com/api-and-mcp/sdk.md), the [CLI](https://docs.avastudio.com/api-and-mcp/cli.md), and agents such as Claude Code and Cursor use Ava. ChatGPT and Claude can connect without a key, with [Sign in with Ava](https://docs.avastudio.com/api-and-mcp/sign-in-with-ava.md).

#### Create a key

1. In Ava Studio, open **Settings > Developers**.
2. Click **Create key** and name it after where it will live, for example "Claude Code on my laptop".
3. Choose its permissions. New keys start with **Read only**; choose **Custom** to enable the permissions your integration needs, or **Full access** to allow every tool.
4. Optionally set a **monthly credit budget**.
5. Copy the key. It starts with `ava_live_` and is shown only once: Ava stores only a fingerprint of it, so a lost key can't be shown again. Create a new one instead.

Creating a key is free and does not require a paid Ava plan. You can have several keys, one per app or script, so each can be limited and revoked on its own. Paid operations need sufficient account credits, including any active [starter credits](https://docs.avastudio.com/api-and-mcp/credits-and-pricing.md#free-accounts-and-starter-credits), and the permissions and budget to use them.

#### Use a key

Send it with every request, in either header:

```
x-api-key: ava_live_…
Authorization: Bearer ava_live_…
```

Keep keys out of code, chats and shared files. Put them in the `AVA_API_KEY` environment variable, as in the [setup snippets](https://docs.avastudio.com/api-and-mcp/connect.md).

#### Permissions

A key can only call the tools its permissions allow; the others are hidden from its tool list and refused with `forbidden`. `jobs_get`, `models_list` and `generation_estimate` work with any key.

| Permission               | What it allows                                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account**              | See the account, credit balance and brand list.                                                                                                 |
| **Read brands**          | List, read and export brand profiles.                                                                                                           |
| **Edit brands**          | Create brand profiles from a website and edit them. Creating uses credits.                                                                      |
| **Research**             | Search short-form video for trends, formats, hooks and breakouts. Uses credits.                                                                 |
| **Read ad results**      | See the Meta connection and your own ad results.                                                                                                |
| **Connect and sync ads** | Get the Meta connect link and sync ad results. Syncing uses credits.                                                                            |
| **Read drafts**          | List and read briefs, shot lists, prompts and Studio links.                                                                                     |
| **Write drafts**         | Draft, clone, revise and score briefs. Uses credits.                                                                                            |
| **Read campaigns**       | List and read campaigns, plan runs, concepts, creatives, Studio projects, templates, voices and library.                                        |
| **Manage campaigns**     | Create and edit campaigns, run Ava's planner, and approve, reject or draft more concepts. Planning and drafting use credits.                    |
| **Produce media**        | Produce media from concepts, generate images, video and audio, create and edit Studio projects and export files.                                |
| **Ask Ava**              | Message Ava, the campaign copilot, as in Studio's Ask Ava panel. She reads your campaigns to answer, even without Read campaigns. Uses credits. |

**Full access** has every permission, including producing media and asking Ava, which spend credits. **Read only** can read your account, brands, ad results, drafts and campaigns, and can't change or spend anything.

The [tool reference](https://docs.avastudio.com/api-and-mcp/tools.md) lists the permission each tool needs.

#### Monthly budgets

A budget limits the new work a key can start in a calendar month (UTC). It counts API charges and credits held by jobs still running. For media, it counts the estimated cost before generation and reconciles completed work within that estimate. A call whose upfront cost would go over the budget is refused with `budget_exceeded` before it runs. Leave it empty for no limit; your plan's balance still applies.

Media generation or repairs can cost more than the estimate, and those additional media credits are still charged to your account. A monthly budget is therefore an admission limit for media work, rather than a guaranteed ceiling on its final cost. Leave a buffer and monitor your account balance when producing media.

You can change a key's budget at any time on the Developers page, which also shows each key's budget usage this month, including running holds and media estimates. `whoami` shows the same numbers for the key that calls it, under `key_budget`.

#### Revoke a key

Click **Revoke** next to the key on the Developers page. It stops working within seconds; jobs it already started keep running. Revoke a key straight away if it may have leaked, then create a new one.
