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.
| Endpoint | Who calls it | What it does |
|---|---|---|
POST /api/agent/provision | Your agent | Creates an invite, emails it, returns a claim_url |
GET /api/agent/provision/lookup?token=… | The activation page | Validates a token and returns a masked email |
POST /api/agent/provision/claim | The human's browser | Sets the password and activates the account |
GET /api/agent/provision/:id | Your agent | Polls 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.
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.
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.
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.
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.
Provisioning is a public write endpoint that sends email, so the limits are tight and worth designing around:
| Rule | Value |
|---|---|
| Invites per IP | 1 per 24 hours |
| Invites per agent key | 5 per 24 hours |
| Pending invites per email | 1 |
| Invite lifetime | 48 hours, then expired |
| Activation attempts | 10 per IP per hour |
| Minimum password | 6 characters |
| Key reveal window | Once, within 1 hour of activation |
| Disposable email domains | Rejected (mailinator, guerrillamail, tempmail, yopmail, and similar) |
Status codes to handle explicitly:
400 — missing or malformed email; a claim without token or with a password under 6 characters.409 — the email already has an account, or a live pending invite exists for it. The response includes provision_id for the pending case, so you can resume polling instead of retrying.429 — IP or per-key limit hit. There is no resend endpoint yet, so treat a lost invite as "wait for expiry or create one with a different key".404 / 410 — bad token, or a token that is already claimed or expired.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.
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.
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 toolboxFull endpoint reference: Agent Hub · OpenAPI spec · llms.txt.