Skip to content

API reference

Authentication

Authenticate every call to the 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 and 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).

When an agent connects through 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.

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:

Shell
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:

Shell
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):

Shell
# 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.