> ## Documentation Index
> Fetch the complete documentation index at: https://docs.migma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Registration

> Let AI agents connect to your Migma account with OAuth or a one-time approval code, no key copying required

<Note>
  Agent registration is in beta.
</Note>

AI agents and MCP clients like Claude, Cursor, and OpenClaw can register themselves with your Migma account. Browser-capable clients can send you through Migma's OAuth consent page. Non-browser agents can show you a short code. In both cases, the agent receives its own scoped API key without you copying or pasting a secret.

## Why use it

<CardGroup cols={2}>
  <Card title="No key handling" icon="key">
    The agent receives its own key directly. The secret never passes through chat, clipboards, or config files you manage by hand.
  </Card>

  <Card title="You approve every agent" icon="user-check">
    Before any access is granted you see the agent's name and exactly which permissions it asked for, then approve it in Migma.
  </Card>

  <Card title="Scoped access" icon="shield-check">
    The key carries only the permissions the agent requested, such as read-only access or sending. Nothing more.
  </Card>

  <Card title="Revoke anytime" icon="ban">
    Agent keys appear in **Settings → Developers → API Keys** next to your own keys. Delete one and the agent loses access immediately.
  </Card>
</CardGroup>

This works with OAuth-capable MCP clients and with any agent that can read a web page. Migma follows the [auth.md](https://workos.com/auth-md/docs) convention, so agents discover and complete the right flow on their own.

## How it works

### OAuth connector approval

<Steps>
  <Step title="Your client asks to connect">
    Add Migma as a connector or hosted MCP server. The client discovers Migma's sign-in and consent flow automatically.
  </Step>

  <Step title="You review and approve">
    Migma opens `migma.ai/connect/authorize`. You see the app name, return host, and requested permissions before approving. Sending access is highlighted as `email:send`.
  </Step>

  <Step title="The client receives its key">
    Once you approve, Migma gives the client a scoped API key automatically. You do not copy or paste a key.
  </Step>
</Steps>

### Claim-code fallback

<Steps>
  <Step title="Your agent asks to connect">
    While working on your behalf, the agent registers with Migma and shows you a short code together with a link to `migma.ai/claim`.
  </Step>

  <Step title="You review and approve">
    Open the link, sign in (or create a free account), and enter the code. Migma shows the agent's name and the permissions it requested before you confirm.
  </Step>

  <Step title="The agent picks up its key">
    Once you approve, the agent automatically receives a scoped API key and continues working. The key is shown to the agent exactly once.
  </Step>
</Steps>

## For agents

Everything an agent needs is published at:

```
https://api.migma.ai/auth.md
```

Machine-readable metadata is at `https://api.migma.ai/.well-known/oauth-authorization-server`. OAuth-capable clients should use the authorization-code flow with PKCE. Agents that cannot open the OAuth consent page can use the claim-code fallback. For that path, `login_hint` is required and must be the email of the user the agent acts for. In short:

```bash theme={null}
# 1. Register intent for the user you act for
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"}'

# 2. Surface claim.user_code and claim.verification_uri_complete to the user

# 3. Poll until approved
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>"}'
```

The returned `access_token` is a standard Migma API key. Use it everywhere a key works: the [REST API](/api-reference/introduction), the [SDK](/sdk), the [CLI](/cli), and [MCP](/mcp-server), typically by setting `MIGMA_API_KEY`.

For the full protocol — discovery endpoints, scopes, code lifecycle, poll-loop error codes, and a complete poll-loop example — see the [agent-auth developer reference](/agent-auth).

## Security

* Claim-code approval requires a signed-in Migma user entering a short-lived code. The email an agent mentions is display only and grants nothing by itself.
* OAuth consent requires a signed-in Migma user approving the client at `migma.ai/connect/authorize`.
* Requested scopes are capped to the standard [API permissions](/authentication) and shown to you before approval.
* Sending access is shown as `email:send`.
* Codes expire after ten minutes and a registration expires after one hour.
* The key is delivered to the agent exactly once and is never shown again.
* Revoke any agent key in **Settings → Developers → API Keys**.