Agent Auth (auth.md) Reference

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. Browser-capable MCP clients should use the OAuth authorization-code flow. Agents that cannot open a browser approval flow can use the claim-code fallback. 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	Dynamic client registration
`POST`	`/agent/identity`	None	10 / 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`	`/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.

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. email:send is highlighted because it allows sending from the account.

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": "audience:read campaign:read email:write"
}

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 open a browser OAuth approval flow.

Step 1 — Register intent

curl -X POST https://api.migma.ai/agent/identity \
  -H "Content-Type: application/json" \
  -d '{
    "type": "service_auth",
    "login_hint": "user@example.com",
    "agent_name": "Claude",
    "scope": "audience:read campaign:read email:write"
  }'

type — required, must be service_auth. Identity-assertion and anonymous registration are not supported yet.
login_hint — required. The email of the user the agent acts for. It is display only; it grants nothing by itself.
agent_name — optional. Shown to the user at approval. Use your product name.
scope — optional, space-delimited. Omit for a read-mostly default. Request only what you need.

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": "audience:read campaign:read email:write",
  "key_name": "Agent: Claude"
}

The access_token is a Migma platform API key and is returned exactly once — store it securely now. 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',
      scope: 'audience:read campaign:read email:write'
    })
  }).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 a read-mostly default; request only the scopes the agent needs. 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 and verification status
`domain:write`	Add, verify, update, and remove sending domains
`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

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

Agent Auth (auth.md) Reference

Discovery

Endpoints

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

​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

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