Agent-native signup and billing

An agent does not need its operator to have an account before it can start. The signup ladder has four rungs; the higher two are API surfaces built for agents. The agent submits the operator’s email plus its own OAuth client identity and a PKCE challenge. The human gets one email and clicks one link; that click is the consent screen and the abuse boundary at once. Nothing provisions before it.

Standard RFC 7591 dynamic client registration:

curl -X POST "https://app.gtm-api.com/id/v4/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My Agent", "redirect_uris": ["http://127.0.0.1:8976/callback"]}'

Keep the returned client_id. Clients born this way are stamped actor_kind: agent, so every token they mint is attributable as agent activity.

Start the registration

curl -X POST "https://app.gtm-api.com/id/v4/auth/register-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "operator@company.com",
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "http://127.0.0.1:8976/callback",
    "code_challenge": "BASE64URL_S256_OF_YOUR_VERIFIER",
    "code_challenge_method": "S256"
  }'

The answer carries registration_sid and a one-time poll_secret. The operator receives a verification email; tell them it is coming.

Poll until the human clicks

curl -X POST "https://app.gtm-api.com/id/v4/auth/register-agent/poll" \
  -H "Content-Type: application/json" \
  -d '{"registration_sid": "id_ar_...", "poll_secret": "..."}'

pending until the operator finishes the page; then {"status": "verified", "code": "...", "team_sid": "ts_tm_..."}. The code is single-use and short-lived; poll again for a fresh one if it expires before you exchange it.

Exchange the code

The standard token endpoint, nothing custom:

curl -X POST "https://app.gtm-api.com/id/v4/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "...",
    "code_verifier": "YOUR_VERIFIER",
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "http://127.0.0.1:8976/callback"
  }'

From here you hold the normal grant credential and installation token: connect to https://mcp.gtm-api.com/mcp or call REST directly. The operator lands in a Sandbox workspace, the forever free plan: one sender slot, no card, no time limit.

Rate limits apply per IP on every endpoint above, the emailed link expires in 24 hours, and an email that already has an account is told so on the verification page, not in the API answer. One live registration per (email, client): re-posting the same pair re-sends the email and answers already_exists: true.

If the operator already has an account, skip this flow: connect through OAuth from any client (Connect a client) and the consent screen does the rest.

When Sandbox is not enough

Sandbox never expires, but verbs answer 402 with subscription_required the moment the workspace needs more than the free plan grants, for example a second connected account or a webhook. That moment is handleable by the agent, not just reportable:

Read the state: search billing-subscriptions for the workspace and see status.
Mint a payment link: create a checkout for the plan through the billing tools (or a Paddle portal link for an existing subscription). Both return a URL a human can open.
Hand the URL to your operator with the one-line reason, and retry the blocked action after the billing-subscriptions.activated webhook, or on your next run.

The agent never touches payment credentials: the link opens Paddle’s checkout in the operator’s browser, and the platform unblocks on the webhook.

​Start a signup for your operator

​When Sandbox is not enough

Start a signup for your operator

When Sandbox is not enough