Skip to main content
An agent key lets an autonomous agent take a real commerce action on your behalf — creating a chargeable payment link for a shopper to pay — within hard limits you set. It is a different capability from the AI keys used to connect an assistant to your analytics and integration data.
Agent keys are not AI keys. An AI key (ai_live_… / ai_sandbox_…) is read-only and reaches only sandbox data — it can never move money. An agent key (agent_live_… / agent_sandbox_…) can create a real, chargeable payment link in production, subject to the spend limits you configure. Choose the AI key for “let an assistant analyze my payments”; choose the agent key for “let an agent transact on my behalf.”

​
Why use it

  • Bounded by design. An agent key can do nothing until you explicitly grant it capabilities — the default grant is read-only. Money-moving access (create_payment_link) is opt-in.
  • Hard spend caps. Every key carries a per-link cap and a daily total cap, in one currency. Both are enforced atomically on the server before a link is created — an agent cannot exceed them, including under concurrent calls.
  • A human still completes the payment. create_payment_link returns a hosted checkout URL. The agent never holds card data and never itself finalizes a charge — the shopper pays through the link.
  • A fixed, closed tool set. Exactly four tools exist behind an agent key today: creating a link, checking a link’s status, listing links, and checking a payment’s status. There is no path to grant an agent key access to any other endpoint.
  • Structurally separate from a secret key. An agent key can never authenticate as your private API key. It is resolved through its own code path and rejected by every other endpoint in the API.
  • Audited. Every tool call an agent key makes — tool name, arguments, outcome — is recorded.

​
Create an agent key

In the Therius dashboard, go to Developers → Agent keys:
1

New agent key

Click New agent key. Give it a label and choose the environment (production or sandbox).
2

Grant capabilities

Select which of the four tools this key may call. Leave create_payment_link unchecked to issue a read-only key.
3

Set spend limits

If you grant create_payment_link, set a per-link cap, a daily total cap, and the currency they’re denominated in. The per-link cap cannot exceed the daily cap.
4

Copy the key

The full key (agent_live_… or agent_sandbox_…) is shown once and cannot be recovered afterward. Store it in a secret manager.
Revoke a key at any time from the same page — revocation is immediate.

​
Connect an MCP client

Point any MCP-capable client at the endpoint shown on the Developers → Agent keys page:
The endpoint speaks JSON-RPC 2.0. Your client discovers the available tools via tools/list — it will see only the tools your key’s capabilities allow.
This is a separate endpoint from the Bring Your Own AI MCP server (ai.therius.io). An agent key only ever authenticates against POST /v1/mcp on the payments API; it is never accepted by the AI-keys MCP server, and an AI key is never accepted here.

​
Tools

A key is issued with the read-only three (get_payment_link_status, list_payment_links, get_payment_status) by default unless you explicitly grant create_payment_link. A successful call returns the link id, its hosted checkout url, and remaining_today — the spend still available under the key’s daily cap.

​
Scope and safety

  • Fixed tool set. The four tools above are the entire surface an agent key can ever reach. There is no way to grant an agent key access to any other endpoint, and the set cannot grow without a Therius code change.
  • Spend is reserved atomically. The per-link and daily-cap check and the spend increment happen in a single database operation — a check can never pass while a concurrent call also passes and together exceed the daily cap.
  • Currency-locked. create_payment_link only accepts the currency configured on the key. There is no cross-currency spend.
  • Scoped to one merchant. An agent key resolves to exactly one merchant. list_payment_links and get_payment_status never return another merchant’s data; a mismatched lookup returns “not found,” not a permission error, so a key can’t even confirm another merchant’s payment exists.
  • Never a secret-key substitute. An agent key is resolved through its own authentication path, entirely separate from your private API key (prv_production_… / prv_sandbox_…). It is rejected by /payment/* and every other endpoint outside /v1/mcp.
  • Environment-bound. agent_live_ keys reach production; agent_sandbox_ keys reach sandbox. There is no cross-over.
  • Audited. Every tool call — tool name, arguments, and outcome — is written to the audit log.