# Migma Agent Registration

Migma is an AI email platform. This file tells agents how to obtain an API credential on behalf of a user, following the [auth.md](https://workos.com/auth-md/docs) convention.

Base URL: `https://api.migma.ai`

Supported flow: **user claimed** (verified by code ceremony). The user must have, or create, a Migma account at `https://app.migma.ai`. Identity-assertion (ID-JAG) and anonymous registration are not supported yet.

## Discovery

Machine-readable metadata:

```
GET https://api.migma.ai/.well-known/oauth-authorization-server
```

The `agent_auth` block lists the endpoints used below.

## Step 1 — Register intent

```
POST https://api.migma.ai/agent/identity
Content-Type: application/json

{
  "type": "service_auth",
  "login_hint": "user@example.com",
  "agent_name": "Claude",
  "scope": "audience:read campaign:read email:send"
}
```

- `login_hint` — the email of the user you act for.
- `agent_name` — shown to the user when they approve you. Use your product name.
- `scope` — optional, space-delimited. Omit for a read-mostly default. Available scopes are listed in `scopes_supported` in the discovery document. Request only what you need.

Response:

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

## Step 2 — Send the user to approve

Show the user `verification_uri_complete` (or `verification_uri` plus the `user_code`). They sign in to Migma (or create an account), review your name and requested scopes, and confirm the code.

## Step 3 — Poll for the credential

```
POST https://api.migma.ai/oauth2/token
Content-Type: application/json

{
  "grant_type": "urn:workos:agent-auth:grant-type:claim",
  "claim_token": "<from step 1>"
}
```

Poll every `interval` seconds. Responses:

- `400 {"error": "authorization_pending"}` — user has not confirmed yet, keep polling.
- `400 {"error": "expired_token"}` — the user code expired. Request a fresh code (Step 4), surface it to the user, keep polling.
- `400 {"error": "invalid_grant"}` — the claim is no longer usable, start over at Step 1.
- `200` — success:

```json
{
  "access_token": "sk_live_…",
  "token_type": "bearer",
  "scope": "audience:read campaign:read email:send",
  "key_name": "Agent: Claude"
}
```

The `access_token` is a Migma platform API key. **It 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`:

```
POST https://api.migma.ai/agent/identity/claim
Content-Type: application/json

{ "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.

## Using the credential

Send it as a bearer token to the Migma API:

```
GET https://api.migma.ai/v1/campaigns
Authorization: Bearer sk_live_…
```

Full API reference: <https://docs.migma.ai>. The API is also available via the Migma MCP server, SDK, and CLI — see <https://docs.migma.ai/mcp>.

## Revocation

The user can revoke the key at any time from their Migma dashboard under API keys. A revoked key fails with `401`; re-register to obtain a new one.