← Back to blog

Provision Human Accounts via API: Magic-Link Onboarding

October 7, 2026 · Eric · 9 min read

Most agent APIs assume the human already has an account. You generate a key in a settings page, paste it into an environment variable, and then the agent goes to work. That assumption breaks the moment you want the agent to do the onboarding itself — a support bot that spins up a teammate, a researcher that signs up the person who asked for the report, or a migration script that creates accounts for twenty people in a spreadsheet.

Agent Media Tools ships a small provisioning flow for exactly that: an agent invites a human by email, the human clicks a magic link and sets a password, and the agent polls until a real API key is available. No SMTP server of your own, no password handling in your code, no OTP screen. Four endpoints and two MCP tools do the whole thing.

The four endpoints

EndpointWho calls itWhat it does
POST /api/agent/provisionYour agentCreates an invite, emails it, returns a claim_url
GET /api/agent/provision/lookup?token=…The activation pageValidates a token and returns a masked email
POST /api/agent/provision/claimThe human's browserSets the password and activates the account
GET /api/agent/provision/:idYour agentPolls status; returns the API key once when claimed

All four are documented in the public OpenAPI spec, so an agent with the spec loaded can discover them without reading this post. The MCP side is provision_human_account and get_provision_status.

Step 1 — Create the invite

Agent → API

email is required. name personalizes the invite email, and agent_label is what the human sees as the sender ("Your Agent") — it also becomes part of the name of the API key the human ends up with.

curl -X POST https://agentmediatools.com/api/agent/provision \
  -H "Authorization: Bearer mt_your_agent_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"alex@example.com","name":"Alex","agent_label":"Invoice Bot"}'

The response is deliberately shareable. The platform emails the invite, and it also hands your agent the same magic link so you can surface it in a chat message if email delivery is slow:

{
  "success": true,
  "provision_id": "9f1c0b5e-1f6a-4a3f-8b2c-2b0f2f43a9d1",
  "status": "pending",
  "email": "alex@example.com",
  "claim_url": "https://agentmediatools.com/activate?token=…",
  "expires_at": "2026-10-09T18:22:04Z",
  "message": "Invite created. Human must open claim_url to verify email and set a password…",
  "email_verification": "Magic link click verifies email — no separate OTP."
}

Two things are worth noticing. First, the Authorization header is optional — the endpoint works unauthenticated, which is why it is guarded by an IP rate limit instead (1 invite per IP per 24 hours). Sending a key is recommended anyway: it raises the per-key allowance to 5 invites per 24 hours and makes the invite pollable only by that key. Second, clicking the link is email verification. There is no separate OTP step to build.

Step 2 — The human activates

The human opens /activate?token=…. That page calls GET /api/agent/provision/lookup?token=… to confirm the invite is still good and to show which email is being verified:

{
  "success": true,
  "valid": true,
  "email_masked": "a***@example.com",
  "name": "Alex",
  "agent_label": "Invoice Bot",
  "expires_at": "2026-10-09T18:22:04Z"
}

Then the page posts the token plus a password to POST /api/agent/provision/claim. Password minimum is 6 characters, and the route rate-limits to 10 attempts per IP per hour. The claim is transactional: the user row, the API key, and the provision record are written together, and the response contains the freshly minted key:

{
  "success": true,
  "status": "claimed",
  "username": "alex",
  "email": "alex@example.com",
  "api_key": "mt_…",
  "api_key_prefix": "mt_a1b2",
  "provision_id": "9f1c0b5e-1f6a-4a3f-8b2c-2b0f2f43a9d1",
  "message": "Account activated. Save the API key now — it is only shown once here and via agent poll."
}

If you would rather keep the human entirely out of the account-creation loop, your agent can do this step itself with token and a password of your choosing — the endpoint is public and takes JSON. Just remember the human then owns an account whose password your agent knows, which you should only do when the human explicitly asked for it.

Step 3 — Poll for the one-time API key

Now the agent polls. This is the part worth automating: a short loop that waits for status: "claimed" and captures the key the first time it appears.

import time
import requests

BASE = "https://agentmediatools.com"
HEADERS = {"Authorization": "Bearer mt_your_agent_key"}

invite = requests.post(
    f"{BASE}/api/agent/provision",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"email": "alex@example.com", "name": "Alex", "agent_label": "Invoice Bot"},
    timeout=30,
).json()

provision_id = invite["provision_id"]
print("Share this link if email is slow:", invite["claim_url"])

api_key = None
for attempt in range(60):                     # up to ~30 minutes
    status = requests.get(
        f"{BASE}/api/agent/provision/{provision_id}",
        headers=HEADERS,
        timeout=30,
    ).json()

    if status.get("api_key"):
        api_key = status["api_key"]
        break

    if status.get("status") in {"expired", "revoked"}:
        raise SystemExit(f"invite is {status['status']} — create a new one")

    time.sleep(30)

if not api_key:
    raise SystemExit("still pending after 30 minutes")

print("Human is onboarded. Key prefix:", api_key[:8])

The poll returns the key once. The route stores the reveal with a one-hour window from activation and clears it after the first successful read:

{
  "success": true,
  "provision_id": "9f1c0b5e-…",
  "status": "claimed",
  "email": "alex@example.com",
  "name": "Alex",
  "agent_label": "Invoice Bot",
  "claimed_at": "2026-10-07 18:31:12",
  "user_id": 4821,
  "api_key_prefix": "mt_a1b2",
  "api_key": "mt_…",
  "api_key_note": "Shown once. Store securely — it will not be returned again."
}

Polling requires a Bearer agent key. If the invite was created with a key, only that key can read it — anything else gets a 403. That matters in multi-tenant setups where several agents share one process: create the invite with the key that will own the follow-up polling.

What the human ends up with

When the claim transaction commits, the new account gets an API key named Agent: Invoice Bot (from your agent_label). The human can rotate or revoke it from their account settings like any other key, and both sides get confirmation email — a welcome message to the human and a claimed-notification with the key prefix.

That naming detail is a feature, not cosmetics. When a human later audits their keys, they can see which one an agent created for them, and revoking it kills that agent's access without touching anything else.

Guardrails and error handling

Provisioning is a public write endpoint that sends email, so the limits are tight and worth designing around:

RuleValue
Invites per IP1 per 24 hours
Invites per agent key5 per 24 hours
Pending invites per email1
Invite lifetime48 hours, then expired
Activation attempts10 per IP per hour
Minimum password6 characters
Key reveal windowOnce, within 1 hour of activation
Disposable email domainsRejected (mailinator, guerrillamail, tempmail, yopmail, and similar)

Status codes to handle explicitly:

Doing it from MCP instead of curl

If your agent already talks MCP, the same flow is available as native tool calls in the Agent Media Tools MCP server: provision_human_account takes email plus optional name and agent_label and returns the claim_url; get_provision_status takes the provision_id and returns the record, including the one-time key. Note that get_provision_status requires the agent key environment variable — polling is authenticated even though invite creation is not.

The trade-off is the same as with any MCP tool call: you get the raw JSON back into the model's context. For an onboarding flow where you also want to email the human a nice message and store the key in a secrets manager, plain HTTP calls from your own code give you more control. For a quick "make my human an account so I can keep working" step inside a chat session, the MCP tools are two calls.

When this is the wrong tool

Be honest about the boundaries before you wire it into a product signup flow:

Within those boundaries it removes the most annoying part of agent onboarding: the hand-off where the human has to go find a settings page, generate a key, and paste it back into a chat where it gets logged. Instead, your agent states the intent, the human clicks one link, and the key arrives where the agent can use it.

Try it in the Toolbox

Create an agent key, then run the same provisioning endpoints by hand from the browser — or hand the whole flow to your agent over MCP.

Open toolbox

Full endpoint reference: Agent Hub · OpenAPI spec · llms.txt.