The agent workflow, from sign-up to live

A coding agent such as Claude Code or Cursor can take your company from no account to a certified sandbox integration on its own. A person steps in only where a person must: to approve the sign-up, to accept the terms and to put money in. This page walks the whole path, step by step, and the guard rails that keep the agent inside it.

Preview. This workflow is not open to customers yet. Agent sign-up, the onboarding manifest, the onboard and mint_api_key tools and scoped agent keys are switched off on the sandbox, and the hosted MCP endpoint is not open. This page describes how the workflow is designed so you can plan for it. The examples use https://YOUR-REST-HOST and https://YOUR-MCP-HOST; the real addresses will be published when the workflow opens. Until then, follow the quick-start with a key from your console.

The path at a glance

Steps 5 to 7 can resume from any session or any agent: the progress lives on the platform, not in the agent.

 Agent                         Platform                         Person (Owner)
   |                               |                                  |
   |-- GET /.well-known/aikonic.json ->|                              |
   |<-- manifest: endpoints, sign-up, defaults                        |
   |                               |                                  |
   |-- POST /v1/signup/device ---->|                                  |
   |<-- user_code, verification_uri, device_code, interval            |
   |   shows the user_code ---------------------------------------->  |
   |                               |<-- opens the consent page -------|
   |                               |--- e-mails a 6-digit code ------>|
   |                               |<-- approves with that code ------|
   |-- POST /v1/signup/device:token (every interval seconds)          |
   |<-- authorization_pending ... then: tenant, sandbox key, MCP endpoint, manifest
   |                               |                                  |
   |== connect to /mcp/public with the sandbox key ==>                |
   |-- onboard -------------------->|                                 |
   |<-- rail, certification, nextCall                                 |
   |-- mint_api_key (narrower) ---->|                                 |
   |<-- a new key, its secret shown once                              |
   |-- search, price, hold, book, cancel (sandbox) ->                 |
   |-- run_missing_certification_checks ->                            |
   |<-- certification passed; rail: needs_you (terms, money)          |
   |                               |<-- accepts terms (e-mailed code)-|
   |                               |<-- funds wallet / saves method --|
   |                               |--- account live, with a daily cap|

1. Discover

The agent is given one address: the onboarding manifest at https://YOUR-REST-HOST/.well-known/aikonic.json. It needs no credential. It lists every environment's API and MCP endpoints, the sign-up routes, the default limits of a new key, the velocity and loop thresholds, the steps to go live, the certification checks, the products and the documentation links. The manifest is signed, so an agent can check that it came from the platform.

2. Start the sign-up over REST

Sign-up happens over REST, not MCP: the agent has no credential yet. It sends the person's work e-mail and, optionally, the company details, and names itself in the X-Agent header:

curl -s -X POST https://YOUR-REST-HOST/v1/signup/device \
  -H "Content-Type: application/json" \
  -H "X-Agent: claude-code/2.1 (claude)" \
  -d '{"email": "[email protected]", "organization": "Example Travel", "country": "GB"}'

The answer follows the OAuth device flow: a device_code for the agent to poll with, a user_code for the person (shown as XXXX-XXXX), the verification_uri of the consent page, expires_in (the request lives 15 minutes) and interval (wait at least 5 seconds between polls). Nothing is created yet.

3. A person approves

The agent shows the person the user_code and the verification_uri. The person opens the consent page on any device, checks who is asking and for which e-mail, and approves with the 6-digit code the platform e-mailed to them. Only the owner of that inbox can create the account.

An agent never approves its own sign-up. The consent page is for a person; the agent has no route to approve, and a sign-up nobody approves expires.

If the e-mail's domain already has an account, nothing new is created: the person is told to ask that account's Owner for an invitation, and the agent's poll answers 409 CONFLICT with nextAction: request_invite.

4. Collect the sandbox key

The agent polls POST /v1/signup/device:token with the device_code:

The approved answer carries the new account, its sandbox key (the secret is shown once, here), the MCP endpoint of the travel tools and the manifest address. It never carries a console session: the person signs in to the console themselves.

5. Connect over MCP

The agent adds the travel tools to its MCP client, exactly as in the quick-start, using the sandbox key:

claude mcp add --transport http travel https://YOUR-MCP-HOST/mcp/public \
  --header "Authorization: Bearer $YOUR_SANDBOX_KEY"

6. Onboard and narrow its own key

The onboard tool (or GET /v1/onboard over REST) answers in one read: the manifest, the account's progress to go-live with the exact item each step still needs, the certification state, and nextCall, the one request that moves the account forward now. nextCall is empty when only a person can act.

Before integrating, the agent mints a key for the job with mint_api_key (POST /v1/keys over REST) and keeps the sign-up key aside. The narrowing rule: a key can only mint a key that is equal or narrower in every dimension. The child's scopes, products and suppliers are a subset of the parent's. Its writes are no higher on the ladder (none, hold, cancel, book with a person's approval, book). Every cap is no higher: spend per day, look-to-book, requests per second, holds per hour, cancellations per day. Its expiry is no later. Asking for more is refused with 403 PERMISSION_DENIED and nextAction: widen_scope_via_owner: only a person can grant more. Every call of a child key also counts against its parent's limits, so minting more keys never multiplies what an agent can do.

7. Certify

The agent runs the sandbox quick-start (search, price, hold, book, cancel). Certification checks turn green from that traffic. For the checks still missing, it calls run_missing_certification_checks (POST /v1/certification:run-missing, sandbox keys only): the platform runs the scenarios for those checks and answers at once; the agent reads the result from the certification state and repeats until every required check has passed.

8. The Owner goes live

When certification passes, the progress shows two steps as needs_you, and both are the Owner's:

1. Accept the terms, confirmed with a code e-mailed to the Owner.

2. Put money in: fund the wallet, or save a payment method.

When both are done the account goes live by itself, with a daily cap you can ask to raise. Live keys are the Owner's to hand out; an agent's live key is minted narrower, and books only with a person's approval by default.

Guard rails

A booking or cancellation needs a person

Over MCP, book_offer and cancel_with_quote never book or cancel. They file a request, and a person on your team approves it in the console; the platform then carries it out once. See how agents stay safe.

Velocity limits pause a looping agent

Every key has its own limits, on top of your account's. A first breach slows the agent down; a repeated one, or a loop, pauses the key:

Retrying with the same Idempotency-Key never counts. A pause charges, holds and cancels nothing; holds already made run to their own expiry. The thresholds above are the planned defaults; the manifest carries the ones in force.

Pause is automatic or a person's; resume is a person's

A paused key answers 423 with nextAction: stop on every call until a person acts, and the error says who can (resumeBy: owner) and links to the console. Only an Owner or Admin resumes a key, in the console, with a reason that is kept on record. No API key and no MCP tool can resume a key: an agent that gets stop stops and tells the person.

Every error says what to do next

Every error body carries nextAction beside code, message and retryable. Over MCP the tool result carries the same body.

A client that does not know a value falls back to code and retryable.

Next steps

• Quick-start: connect a client and make the first search, hold and booking request.

• Overview: the toolsets, how agents sign in, limits and every error code.

• Reference: onboarding tools, including onboard, mint_api_key and run_missing_certification_checks; travel tools for everything after.