Agent identity

An agent that calls the platform can say who it is, and a person who approves something can see who asked. This page covers the three identities on every call, how to prove them, the trust tiers, how to register your agent and how to watch it. How an agent finds the platform is on its own page: how agents find the platform.

Rolling out. Everything on this page is being rolled out: discovery documents come first on the sandbox, then agent registration and request signing. Each is off until it is switched on, and the changelog says when. The examples use synthetic values: example.com domains and [email protected].

Find the platform

An agent needs one address, the AI Catalog, and no credential:

https://aikonic.travel/.well-known/ai-catalog.json

The whole picture, from Server Cards and sign-in metadata to the MCP Registry and DNS, is in how agents find the platform.

Three identities on every call

Identity tells the platform who is calling. It never grants anything. Permissions come only from the key's scopes or from the grant the person approved, and a person still approves every booking or payment. A verified identity never adds a permission.

Prove who you are

An agent can prove its identity in two ways. Neither is required to call the API.

Sign your requests

Sign requests with HTTP Message Signatures (RFC 9421), following the Web Bot Auth profile.

1. Publish your public keys as a JWKS at https://<your-domain>/.well-known/http-message-signatures-directory. Serve it with 200 and no redirects.

2. Send Signature-Agent: "https://<your-domain>" on each request.

3. Send Signature-Input with tag="web-bot-auth", keyid set to the JWK thumbprint and created set to the signing time. A signature is accepted up to 300 seconds after created and up to 30 seconds before it (clock skew).

4. Cover @authority, @method, @path and signature-agent. On a request with a body, also cover content-digest.

5. Optionally send Agent-Version. It counts only when it is covered by the signature.

A complete request, with a synthetic signature:

POST /v1/search HTTP/1.1
Host: YOUR-REST-HOST
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Content-Digest: sha-256=:4p6AAiozFiU7q+nTurYMLJfOGPB6HRYFkDMY5pLUxNw=:
Signature-Agent: "https://skyhop.example"
Agent-Version: 2.4.0
Signature-Input: sig1=("@authority" "@method" "@path" "signature-agent" "content-digest" "agent-version");created=1767225600;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U";alg="ed25519";tag="web-bot-auth"
Signature: sig1=:EXAMPLEc2lnbmF0dXJlLXZhbHVlLWZvci1kb2N1bWVudGF0aW9uLW9ubHk=:

{"context":{"domain":"FLT","currency":"USD"},"message":{"intent":{"slices":[{"origin":"GRU","destination":"MIA","date":"2026-11-10"}],"travelers":[{"type":"ADT"}],"cabin":"ECONOMY"}}}

Identify an OAuth client

An OAuth client uses a Client ID Metadata Document: the client_id is the HTTPS URL of a document you host, for example https://skyhop.example/oauth/client.json. The platform fetches it and shows the person who is asking on the consent screen.

What a bad signature does

A wrong signature is refused with 401 UNAUTHENTICATED, details.reason AGENT_SIGNATURE_INVALID and nextAction: reauth. An unsigned request is never refused for that alone.

Trust tiers

A higher tier means less friction and a "Verified" badge on consent and approval screens. On production an unverified (T0) caller is limited to read tools and gets grants of one hour at most; holds and proposals need T1. A call that needs more is refused with 403 PERMISSION_DENIED, details.reason AGENT_TIER_INSUFFICIENT and nextAction: verify_agent. Sandbox and trial accounts have no tier limit. Tiers are not sold: they are earned by verification.

Register your agent

Owners and Admins register agents in the console under Developer, Agent registry.

• Handle. name@your-domain, or a hosted handle name@<account>.agents.aikonic.travel. A name uses a-z, 0-9 and hyphens, 2 to 32 characters. The names admin, support, booking, aikonic and security are reserved: 422 VALIDATION with HANDLE_RESERVED. A handle already taken, or a look-alike of another account's verified handle, is refused with 409 CONFLICT and HANDLE_TAKEN.

• Domain proof. Publish a TXT record at _aikonic-verify.<domain> with the value av=<agentId>, for example _aikonic-verify.skyhop.example = av=agent_example. It is rechecked daily; if the record disappears, the agent drops to T0.

• Versions. Register each release with its semantic version, model id and prompt hash. A version can be drained (no new work) or revoked. A revoked version's next request is refused with 401 UNAUTHENTICATED and AGENT_VERSION_REVOKED, and its grants end within 10 minutes. Proposals already waiting for a person stay.

• Keys. Bring your own public key or key directory URL, or let the console generate a key pair in your browser: the private key is shown once and never sent to the platform. Rotate a key with a 7-day overlap so both keys verify while you deploy.

• Private agents. A private agent is never published or resolvable.

Look up an agent

GET /v1/agents:[email protected] is public and rate-limited. The MCP resource resolve_agent returns the same profile: handle, operator, tier, current version, protocols, key thumbprints, certificate validity and the public log. It never shows the person an agent acts for, account ids or traffic.

curl -s "https://YOUR-REST-HOST/v1/agents:[email protected]"

The travel agent directory, GET /v1/agents:search and the MCP tool search_agent_directory, lists verified travel agents, ranked by capability and outcomes, never by payment. It is being rolled out.

Watch your agents

• Agent traffic. The console shows calls by tier and proof, signature failures and a 24-hour trend.

• Request trace. Each request shows the seven checks it passed or failed.

• Webhooks. agent.registered, agent.version_registered, agent.version_revoked, agent.key_rotated, agent.tier_changed and agent.suspended.

Third-party text is data

Names and card text that come from other parties are shown as plain text. The platform and the agents that use it never follow them as instructions.

Next steps

• Agent workflow: from sign-up to a live account.

• Quick-start: connect a client and make the first search.

• Overview: toolsets, how agents sign in, limits and error codes.

• Travel tools: everything an agent can call.