---
title: API keys
description: Create a key to call the AdCrunch REST API from your own code, understand whose permissions it uses and when it stops working, and revoke it.
---

import Callout from '#docs/components/mdx/callout.astro';
import Steps from '#docs/components/mdx/steps.astro';
import Step from '#docs/components/mdx/step.astro';

An **API key** lets your own code call AdCrunch. Use one for a script, a scheduled job, or a backend service — anywhere no person is present to sign in.

You do not need a key to connect an AI agent. Claude, Cursor, and ChatGPT connect over MCP and sign in through your browser. See [Auth & scopes](/mcp/auth) for that. A key is for code you write.

## Create a key

1. **Open Settings, then API keys**

    Go to [the console](https://console.adcrunch.dev), then **Settings → API
    keys**. The page lists the keys your organization has, when each was
    created, when each was last used, and when each expires.

2. **Name the key for the job that will use it**

    "Nightly budget sync" tells you which job stops if you revoke that key. "Key
    1" does not.

3. **Choose when it expires**

    30 days, 60 days, 90 days, one year, or never. The default is **90 days**. A
    key that expires stops working on that date, so put the date in your
    calendar with the job that uses it.

4. **Copy the key**

    The key appears once. AdCrunch stores a hash of it, so nobody can show it to
    you again — not you, and not AdCrunch support. Copy it into your secret
    store now. If you lose it, revoke it and create another.

> **A key can change your ad accounts**
>
> A key can pause a campaign, raise a budget, and create ads. Handle it as you
> handle a payment credential. Do not commit it, do not put it in a browser, and
> do not paste it into a page that asks for it.

## Whose permissions a key uses

A key acts as the **organization** that was active when you created it, with the permissions of the **person who created it**.

Three consequences matter before you build on one.

- **The organization is fixed.** A key keeps acting on the organization it was created for, whatever you switch to afterwards. It cannot reach another one.
- **The creator's permissions are read on every request, not copied.** Change that person's role and the key changes with it, immediately.
- **The key stops working if the creator leaves the organization.** AdCrunch finds no membership, grants nothing, and every request answers `403`. Deleting the creator's account answers `401` instead. Neither the key nor the job that uses it reports this in advance.

> **Create keys from an account that stays**
>
> A key created by somebody who later leaves takes their job down with them. For
> a job that has to keep running, create its key from an account that is not
> tied to one person's employment.

## Use a key

Send it as a bearer token:

```bash
curl https://api.adcrunch.dev/observe/campaigns \
  -H "Authorization: Bearer acr_your_key_here"
```

Every AdCrunch REST API takes the same header. The [API reference](/api) lists the endpoints.

## Revoke a key

Revoke a key from the same page. It stops working immediately, and anything still using it receives `401`.

Revoke one when its job is retired, when somebody with access to it leaves, and the moment you think one has leaked. To replace a key without stopping the job, create the new key first, deploy it, and revoke the old one after.

> **One key for each job**
>
> Separate keys let you revoke one job's access without touching the others, and
> the name in the list tells you which job you are about to stop.