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

# API keys

> Create, list and revoke personal and organization API keys for scripts and service-to-service integrations.

API keys are bearer credentials for headless work: scripts, back-office jobs and agents that call the
REST API or `/mcp/v3` without a person signing in. Every request sends
`Authorization: Bearer <key>`. For interactive clients, prefer OAuth (see
[Authentication](/v3/authentication)).

There are two kinds:

| Kind                     | Owned by         | Acts as                                                                      | Who can create |
| ------------------------ | ---------------- | ---------------------------------------------------------------------------- | -------------- |
| **Personal API key**     | You              | You, with your **current** role. If you leave the account, it stops working. | Any member     |
| **Organization API key** | The organization | An account admin, across every advertiser. It survives people leaving.       | Account admins |

Prefer a personal key for your own scripts: it can never do more than you can. Use an organization key
for shared service integrations, and keep it in a secret manager.

## Create a key

Create keys in the app: open **Settings → API keys**. Behind it are `POST /api/v2/user-api-keys` for a
personal key and `POST /api/v2/org-api-keys` for an organization key. Both need a signed-in person: a
request authenticated with an API key is refused ("Sign in as a user to do that."), so a key can't
create another key.

```json theme={null}
{ "name": "Nightly reporting export", "expiresAt": "2027-06-30T00:00:00Z" }
```

The body is the same for both:

| Field       | Notes                                                     |
| ----------- | --------------------------------------------------------- |
| `name`      | Required, up to 100 characters.                           |
| `expiresAt` | Optional. Must be in the future and at most one year out. |

The response includes the full `secret`, which starts with `sck_`.

<Warning>
  The secret is shown **once**, in the create response. Semicola stores only a hash and can't show it
  again. If you lose it, revoke the key and create a new one. Never commit keys to git.
</Warning>

## List keys

* `GET /api/v2/user-api-keys` lists your personal keys.
* `GET /api/v2/org-api-keys` lists every key on the account for an admin, and only your own for
  anyone else.

Each key shows its `id`, `name`, `prefix` (the non-secret start of the key, safe to log), the owner,
`lastUsedAt`, `expiresAt` and `createdAt`. The secret is never listed.

## Revoke a key

`DELETE /api/v2/user-api-keys/{id}` or `DELETE /api/v2/org-api-keys/{id}`. Revoking takes effect at
once. Admins can revoke any key on the account; members only their own. A revoked or expired key is
refused like an unknown one.

## Keys for buyer agents

A key registered to a buyer agent authenticates only as that agent, with the per-advertiser grants you
gave it, never as the account. See [Buyer agent credentials](/v2/setup/buyer-agent-credentials).

## Not available yet

* Keys scoped to a single advertiser with their own role; use a buyer agent credential with a
  per-advertiser grant instead.
* Rotating a key in place. Create the new key, switch your integration to it, then revoke the old one.

## Related

* [Authentication](/v3/authentication)
* [Account access](/v3/account-access)
* [Activity and audit logs](/guides/audit-logs): every call a key makes is recorded under Calls.