Migma Agent Authentication Protocol

Agent registration is in beta. For the user-facing overview of how approval works, see Agent registration. This page is the deeper protocol reference for developers building agents.

Migma follows the auth.md convention, so an agent can discover the flow and obtain its own scoped API key without a human copying a secret. MCP clients that can complete a browser redirect/callback should use the OAuth authorization-code flow. Direct clients that cannot complete that callback but can call the API, poll, and securely store a credential can use claim-code. Base URL: https://api.migma.ai The skill file an agent reads is served at https://api.migma.ai/auth.md.

Discovery

Agents discover the endpoints and supported scopes from the well-known metadata. The agent_auth block in the authorization-server document lists the claim and identity endpoints.

GET https://api.migma.ai/.well-known/oauth-authorization-server
GET https://api.migma.ai/.well-known/oauth-protected-resource
GET https://api.migma.ai/.well-known/oauth-protected-resource/mcp

The authorization-server document includes scopes_supported, authorization_endpoint, registration_endpoint, token_endpoint, grant_types_supported, PKCE support, and the agent_auth endpoint map. An agent that hits a protected API without a valid key receives 401 with a WWW-Authenticate challenge that points back to the protected-resource metadata, so it can find this flow:

WWW-Authenticate: Bearer resource_metadata="https://api.migma.ai/.well-known/oauth-protected-resource"

The MCP endpoint returns the same challenge pointing at its own resource metadata (/.well-known/oauth-protected-resource/mcp).

Endpoints

Method	Path	Auth	Rate limit	Purpose
`GET`	`/auth.md`	None	—	The agent skill file
`GET`	`/.well-known/oauth-authorization-server`	None	—	Authorization-server metadata (scopes, endpoints)
`GET`	`/.well-known/oauth-protected-resource`	None	—	Protected-resource metadata for the API
`GET`	`/.well-known/oauth-protected-resource/mcp`	None	—	Protected-resource metadata for the MCP server
`GET`	`/oauth2/authorize`	None	30 / 5 min per IP	Start the OAuth authorization-code flow
`POST`	`/oauth2/register`	None	10 / hour per IP	Optional dynamic client registration; supplies the name shown on the approval page
`POST`	`/agent/identity`	None	60 / hour per IP	Step 1 — register intent, get a claim token and user code
`POST`	`/agent/identity/claim`	None	20 / hour per IP	Step 4 — refresh an expired user code
`POST`	`/agent/identity/signup`	None	10 / hour per IP	First-party clients only — create an account in-product
`POST`	`/oauth2/token`	None	120 / 5 min per IP	Exchange an authorization code or poll a claim token

The claim page endpoints (/agent/identity/claim/lookup and /agent/identity/claim/complete) are used by the Migma web UI when the user enters their code. Agents do not call them.

First-party clients

A host-app extension published by Migma — today the Figma plugin — registers with client_id instead of login_hint, because it runs inside another product and cannot know the user’s Migma account until they approve. The server, not the client, then decides the display name, the key name and the scopes, so a first-party client cannot widen its own grant:

curl -X POST https://api.migma.ai/agent/identity \
  -H "Content-Type: application/json" \
  -d '{ "type": "service_auth", "client_id": "figma-plugin" }'

Everything else is the claim-code flow above. Those clients meet people who have no Migma account at all, and sending them to a registration form in another window loses most of them. POST /agent/identity/signup creates the account where they already are:

curl -X POST https://api.migma.ai/agent/identity/signup \
  -H "Content-Type: application/json" \
  -d '{
    "claim_token": "<from /agent/identity>",
    "email": "designer@studio.com",
    "first_name": "Alex",
    "last_name": "Rivera",
    "website": "studio.com",
    "marketing_consent": false
  }'

claim_token — required. Must belong to a pending, unexpired registration made by a first-party client_id; anything else is rejected.
email — required. A conflict with an existing account answers 409 account_exists.
first_name — required. last_name and website are optional; website seeds the brand import and is normalised to a hostname.
No password is accepted. The account is created passwordless and the person receives a link to set one, which also proves they own the address.

{ "status": "claimed", "account": { "email": "designer@studio.com", "first_name": "Alex" } }

The response deliberately carries no credential. Signing up claims the registration; the client then collects the key from POST /oauth2/token exactly as it would after a browser approval, so a key is minted in one place regardless of how the account came to exist. This endpoint is not open to third-party agents, and it can be switched off server-side with AGENT_AUTH_SIGNUP_ENABLED=false without affecting sign-in for existing accounts.

Authorization-code flow

Use this OAuth path for MCP clients that can open a browser approval flow.

Discover Migma auth metadata

Read https://api.migma.ai/.well-known/oauth-authorization-server to find the registration, authorization, token, and scope metadata.

Register with a client name and redirect URI. Migma supports public clients with authorization_code, code, and token_endpoint_auth_method: none. Redirect URIs must use HTTPS, except localhost and 127.0.0.1 may use HTTP for local clients.

Start authorization with PKCE

Send the user through the authorization endpoint with response_type=code, the registered client_id, redirect_uri, requested scope, and PKCE S256. PKCE is required.

User approves on Migma

Migma shows the consent page at migma.ai/connect/authorize. The user signs in, reviews the client name, return host, and requested scopes, then approves or denies access. Migma marks email:send and campaign:write as delivery access.

Exchange the code

Exchange the code at the token endpoint with the same client_id, redirect_uri, and PKCE verifier. The response contains a scoped Migma API key in access_token.

Success body:

{
  "access_token": "sk_live_…",
  "token_type": "bearer",
  "scope": "email:read email:write campaign:read"
}

The key works anywhere a Migma API key works, including the hosted MCP server. It appears in Settings → Developers → API Keys and can be revoked there. No refresh token is issued.

Claim-code fallback

Use this path when the agent cannot complete a browser OAuth redirect/callback but can call the API, poll, and securely store the once-only credential. Claim-code does not repair a broken hosted connector.

Step 1 — Register intent

curl -X POST https://api.migma.ai/agent/identity \
  -H "Content-Type: application/json" \
  -d '{
    "type": "service_auth",
    "agent_name": "Claude"
  }'

type — required, must be service_auth. Identity-assertion and anonymous registration are not supported yet.
login_hint — optional. The email of the user the agent acts for, shown on the approval page. It is display only; identity binds to whoever signs in and approves.
agent_name — optional. Shown to the user at approval. Use your product name.
scope — optional, space-delimited. Omit it for the full permission set; the approval page is the gate. Pass it only to narrow access.

Response:

{
  "claim_token": "<JWT, keep private>",
  "claim": {
    "user_code": "XXXX-XXXX",
    "verification_uri": "https://migma.ai/claim",
    "verification_uri_complete": "https://migma.ai/claim?code=XXXX-XXXX",
    "expires_in": 600,
    "interval": 5
  }
}

Step 2 — Send the user to approve

Surface verification_uri_complete (or verification_uri plus user_code) to the user. They sign in to Migma, review the agent name and requested scopes, and confirm the code.

Step 3 — Poll for the key

Poll the token endpoint every interval seconds (default 5):

curl -X POST https://api.migma.ai/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:workos:agent-auth:grant-type:claim",
    "claim_token": "<from step 1>"
  }'

Responses:

Status	`error`	What to do
`400`	`authorization_pending`	The user has not confirmed yet. Keep polling.
`400`	`expired_token`	The user code expired. Refresh it (Step 4), surface the new code, keep polling.
`400`	`invalid_grant`	The claim is no longer usable. Start over at Step 1.
`200`	—	Success. The key is in `access_token`.

Success body:

{
  "access_token": "sk_live_…",
  "token_type": "bearer",
  "scope": "email:read email:write campaign:read",
  "key_name": "Agent: Claude"
}

The access_token is a Migma platform API key and is returned exactly once. Keep it and claim_token out of chat, logs, shell history, and shared files. If the client cannot do that, stop before registration. Further polls return invalid_grant.

Step 4 — Refresh an expired user code

Only when polling returned expired_token:

curl -X POST https://api.migma.ai/agent/identity/claim \
  -H "Content-Type: application/json" \
  -d '{ "claim_token": "<from step 1>" }'

Returns a fresh claim object with a new user_code. The whole registration expires one hour after Step 1; after that, start over.

Code lifecycle

The user_code expires after expires_in seconds (600 by default).
Refresh an expired code with POST /agent/identity/claim using the same claim_token.
The whole registration expires one hour after Step 1.
The access_token is issued exactly once; re-polling after issuance returns invalid_grant.

Poll loop example

async function registerAgent(loginHint) {
  const intent = await fetch('https://api.migma.ai/agent/identity', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      type: 'service_auth',
      login_hint: loginHint,
      agent_name: 'Claude'
    })
  }).then((r) => r.json());

  let { claim_token, claim } = intent;
  console.log('Approve at:', claim.verification_uri_complete);

  while (true) {
    await new Promise((r) => setTimeout(r, claim.interval * 1000));

    const res = await fetch('https://api.migma.ai/oauth2/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        grant_type: 'urn:workos:agent-auth:grant-type:claim',
        claim_token
      })
    });
    const body = await res.json();

    if (res.ok) return body.access_token; // sk_live_…

    if (body.error === 'authorization_pending') continue;

    if (body.error === 'expired_token') {
      const refreshed = await fetch('https://api.migma.ai/agent/identity/claim', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ claim_token })
      }).then((r) => r.json());
      claim = refreshed.claim;
      claim_token = refreshed.claim_token;
      console.log('New code:', claim.verification_uri_complete);
      continue;
    }

    // invalid_grant or anything else — start over
    throw new Error(`Registration failed: ${body.error}`);
  }
}

Scopes

Scopes are space-delimited in the scope field of Step 1. Omit the field for the full permission set — the approval page lists every permission and marks send as destructive. Pass an explicit list to narrow access. The available scopes are published in scopes_supported in the discovery document:

Scope	Grants
`audience:read`	View subscribers, tags, and segments
`audience:write`	Add and update subscribers, manage tags, create segments
`email:read`	View emails and sending history
`email:write`	Create and edit generated emails
`email:send`	Send test and live emails
`email:validate`	Run compatibility, link, and deliverability checks
`email:preview`	Generate device and client previews
`domain:read`	View sending domains, verification and purchase status, and custom DNS on domains bought in Migma
`domain:write`	Add, verify, update, and remove sending domains; buy a domain (Stripe checkout the account owner opens); manage custom DNS on domains bought in Migma
`campaign:read`	View campaigns and their stats and logs
`campaign:write`	Create, send, schedule, and manage campaigns
`webhook:read`	List and view webhooks
`webhook:write`	Create, update, and delete webhooks
`project:write`	Import projects and manage project resources
`billing:read`	View plan and credits
`billing:write`	Create billing links (Stripe checkout and portal) that the user opens and approves themself

email:send allows test and direct email. campaign:write allows campaign creation, send, and schedule. Even with a full-permission credential, agents confirm sends with the user in the conversation.

Omitted scope includes both billing scopes on every path.

Using the credential

The access_token is an ordinary Migma API key. Send it as a bearer token and discover a project to work in:

# 1. List projects to get a projectId
curl https://api.migma.ai/v1/projects?limit=1 \
  -H "Authorization: Bearer sk_live_…"

# 2. Use that projectId on project-scoped requests
curl "https://api.migma.ai/v1/campaigns?projectId=PROJECT_ID" \
  -H "Authorization: Bearer sk_live_…"

The key is account-scoped, so pass projectId per request; a resource in a project you did not name returns 404. The key works everywhere a Migma key works: the REST API, the SDK, the CLI, and MCP, typically by setting MIGMA_API_KEY.

Revocation

Agent keys appear in the Migma dashboard under Settings → Developers → API Keys alongside your own keys. The user can revoke one at any time. A revoked key fails with 401; the agent should re-register to obtain a new one.

Getting Started

Tools

MCP Clients

AI App Builders

Agent Access

Migma Agent Authentication Protocol

Discovery

Endpoints

First-party clients

Authorization-code flow

Claim-code fallback

Step 1 — Register intent

Step 2 — Send the user to approve

Step 3 — Poll for the key

Step 4 — Refresh an expired user code

Code lifecycle

Poll loop example

Scopes

Using the credential

Revocation

​Discovery

​Endpoints

​First-party clients

​In-product sign-up

​Authorization-code flow

​Claim-code fallback

​Step 1 — Register intent

​Step 2 — Send the user to approve

​Step 3 — Poll for the key

​Step 4 — Refresh an expired user code

​Code lifecycle

​Poll loop example

​Scopes

​Using the credential

​Revocation

Discovery

Endpoints

First-party clients

In-product sign-up

Authorization-code flow

Claim-code fallback

Step 1 — Register intent

Step 2 — Send the user to approve

Step 3 — Poll for the key

Step 4 — Refresh an expired user code

Code lifecycle

Poll loop example

Scopes

Using the credential

Revocation