# Authentication

Authenticate Mestra API requests with a key: what a key can do, who can make it, and how it expires.

Authenticate every call to the [API](https://withmestra.com/docs/api/) with a key, sent as `Authorization: Bearer <key>`. Keys start `ptk_`. A key can only do what you let it.

## What a key can do

When you make a key, you choose what it can do. Pick a preset, or set permissions area by area.

| Preset     | What it can do                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Read**   | Read campaigns, runs, reviews, usage and brand, as far as its role may see. Not team or settings. Never changes anything. |
| **Write**  | Read, plus do work: runs, reviews, comments, exports and campaigns. It doesn't change the organisation.                   |
| **Admin**  | Write, plus change the organisation: brand, team, settings and screens. Owners only.                                      |
| **Custom** | Read and/or write for each area: campaigns, runs, reviews, brand, team, settings and designs. Usage is read only.         |

The areas you can set are campaigns, runs, reviews, brand, team, settings, usage and **Designs**. Designs is read and write: read opens a size or master for editing and looks at it, and write makes edits and saves them. See [Editing a size](https://withmestra.com/docs/api/editing-a-size/) and [Editing a master](https://withmestra.com/docs/api/editing-a-master/). The presets don't include Designs. To use it, choose **Custom** and tick it. A key that opens a size or master for editing needs a write permission somewhere as well as Designs · Read.

Keys made before Admin included Write keep the permissions they were made with. To get the new Admin, make the key again, or reconnect the assistant. For a key that only changes settings, choose **Custom**.

Write on an area includes read. Brand, team and settings write are admin areas, and only an owner can grant them. Only an owner can grant the Mestra Player **Screens** permissions too (see the [Player API reference](https://withmestra.com/docs/player/api/)).

When an agent connects through [MCP](https://withmestra.com/docs/mcp/), it asks for the scope `mcp:designs` to edit designs. The consent screen then starts from custom permissions: the write set plus Designs · Write.

An installation partner can tick **Include linked customers** when it makes a key. It extends the key's **Screens** permissions to every customer linked to the partner's organisation, and never reaches anything else of theirs. A key with it shows **Includes linked customers**. See [Installation partners](https://withmestra.com/docs/player/partners/#api-keys).

A call the key's permissions don't cover answers `403` with the code `wrong_key`, and says what the key needs. A key also keeps its owner's role (Reviewer, Editor or Owner), and a call needs both.

## User keys and service keys

- A **user key** acts as the person who made it, in their organisation, with their role. If the person leaves the organisation, their keys stop working. Anyone can make a key of their own with read or write permissions. Only an owner can grant admin areas.
- A **service key** belongs to the organisation itself and keeps working when people leave. Only an owner can make a service key.

## Expiry

When you make a key, you can set it to expire after 1 to 3,650 days, or never. An expired key answers `401`.

## Making and stopping keys

Keys are made only in Mestra, in **Developer** > **API and MCP**, while you're signed in. There is no call that makes a key. The key is shown once.

If an owner turns the API off, every key is revoked, and calls answer `409` with the code `api_off`. When it is back on, make new keys.

## Sign in from CI without a key

A CI job or cloud workload can swap its own identity for a short-lived Mestra token, so no key is stored anywhere.

An owner adds the workload in **Developer** > **API and MCP** > **Workloads**:

1. Choose a provider: GitHub Actions, Google Cloud, AWS or Other (OIDC).
2. Say which workload it is. GitHub: the repository, plus a branch, tag or environment. Google Cloud: the service account unique ID. AWS: the issuer and the role ARN. Other: the issuer and the subject.
3. Choose its permissions, as for a key.

Each workload gets its own audience URL. Copy it into the job.

The job asks its provider for a token with that audience, then posts it to `https://app.withmestra.com/oauth/token`. The answer holds an `access_token`, which lasts 1 hour. Send it as `Authorization: Bearer` on `/api/v1` and `/mcp`. A refused token answers `400` with `invalid_grant`.

Removing the workload, or turning the API off, stops its tokens at once.

GitHub Actions:

```yaml
permissions:
  id-token: write
steps:
  - run: |
      JWT=$(curl -sS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=AUD" | jq -r .value)
      MESTRA_TOKEN=$(curl -sS https://app.withmestra.com/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange -d subject_token_type=urn:ietf:params:oauth:token-type:jwt --data-urlencode "subject_token=$JWT" | jq -r .access_token)
```

Google Cloud:

```sh
JWT=$(curl -sS -H "Metadata-Flavor: Google" "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUD")
MESTRA_TOKEN=$(curl -sS https://app.withmestra.com/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange -d subject_token_type=urn:ietf:params:oauth:token-type:jwt --data-urlencode "subject_token=$JWT" | jq -r .access_token)
```

AWS:

```sh
JWT=$(aws sts get-web-identity-token --audience AUD --signing-algorithm RS256 --query WebIdentityToken --output text)
MESTRA_TOKEN=$(curl -sS https://app.withmestra.com/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange -d subject_token_type=urn:ietf:params:oauth:token-type:jwt --data-urlencode "subject_token=$JWT" | jq -r .access_token)
```

Other (OIDC):

```sh
# JWT = your provider's token for audience AUD
MESTRA_TOKEN=$(curl -sS https://app.withmestra.com/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange -d subject_token_type=urn:ietf:params:oauth:token-type:jwt --data-urlencode "subject_token=$JWT" | jq -r .access_token)
```

Replace `AUD` with the audience URL Mestra shows you.

Provider notes:

- **GitHub:** repositories created after 15 July 2026 use subjects with the owner and repository IDs, so enter the IDs for those.
- **AWS:** the account must have outbound identity federation enabled (`aws iam enable-outbound-web-identity-federation`). Get the issuer from `aws iam get-outbound-web-identity-federation-info`.
- **Other (OIDC):** any provider whose tokens can carry a custom audience and that publishes `/.well-known/openid-configuration` over https.

If a call fails, see [Errors](https://withmestra.com/docs/api/errors/).
