Authentication

Every request to the GTMify API carries an API key as a bearer token. Keys are issued from the GTMify app, belong to one organization, and carry a list of scopes that decide what the key may do.

Get a key

Open app.gtmify.io/developers/keys while signed in. Only an organization owner or admin can create, rotate, edit or revoke keys; other members see a note asking them to request one from their owner.

Each key is bound to the organization that issued it and can only reach that organization's data. The full key is shown once, when you create or rotate it, so store it in a secret manager at that moment. A rotated or revoked key stops working immediately.

Send the key

Send the key in the Authorization header. The base URL is https://app.gtmify.io/v1, and every path in the reference is relative to it.

curl https://app.gtmify.io/v1/campaigns \
  -H "Authorization: Bearer gtm_live_YOUR_KEY"

A request without a valid key, or with a key that lacks the scope an operation needs, is rejected. Each operation in the reference names the scope it requires.

Scopes and tiers

When you create a key you choose its scopes. Grant the smallest set the client needs. Every scope carries a blast radius tier, shown below. The table is generated from the live API specification, so it always matches the reference.

Tier 1 is a read with no state change.
Tier 2 is a reversible, draft-shaped write with no external effect.
Tier 3 causes an external effect or spends credits, such as approving content to send or sending. A human must approve it.

Do not put a tier 3 scope on an agent key. An autonomous agent should draft and read, and a person should hold the steps that send, approve or spend. The app does not yet block you from selecting a tier 3 scope on a key, so this is on whoever issues the key. No published operation currently requires a tier 3 scope.

Scope	Tier	What it allows
`brand_voices:read`	1	Read brand voices and their generated instructions for the organization.
`campaigns:read`	1	Read campaigns, their status, and metrics for the organization.
`intelligence:read`	1	Read account, business, and market intelligence for the organization.
`leads:read`	1	Read leads and their generated step content for the organization.
`sources:read`	1	Read source metadata (title, type, status, word count, external_ref) for the organization, so an importer can reconcile what it has already sent. Never returns transcript text.
`brand_voices:write`	2	Create brand voices and update their name, description, type, language, artefacts and instructions. Does not run a generation or spend credits.
`campaigns:write`	2	Create and update campaigns and their settings. Does not mark ready, launch or send; marking ready creates the vendor campaign and is a tier 3 action.
`content:write`	2	Create and edit lead step content. Edited content stays in review until a human approves it. Brand voices are written under brand_voices:write.
`intelligence:write`	2	Create, update, and generate account, business, and market intelligence for the organization.
`leads:write`	2	Import and update leads, and move them through lifecycle stages up to approval_pending. Cannot approve content or send.
`sending_profiles:write`	2	Set which languages a sending profile may send in, map it to its Lemlist user, and assign a sending profile to a campaign. Does not provision mailboxes, register sending domains or send.
`sources:write`	2	Import long-form source material, such as call transcripts, into the Idea Bank's intake. Imported sources are held for human review before they can be mined.
`suppression:write`	2	Add leads and domains to the organization's suppression list, which stops sending to them. Add only: removing a suppression re-enables sending to someone who may have opted out and stays in the app.
`content:approve`	3	Move lead step content from approval_pending to approved, which makes it eligible to send. High blast radius: human approval is required, and this scope must not be granted to an autonomous agent key.
`jobs:run`	3	Trigger the idempotent background jobs (enrich, generate content, sync metrics). Each run spends the organization's credits. High blast radius: human approval is required, and this scope must not be granted to an autonomous agent key.
`send:execute`	3	Push approved leads and content to execution channels (Lemlist, Instantly), which sends to real recipients. High blast radius: human approval is required, and this scope must not be granted to an autonomous agent key.

16 scopes are currently defined.