> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Keys: Let an AI Agent Conduct Bounded Commerce

> Give an autonomous agent a scoped, spend-capped key that can create real payment links over MCP — distinct from the read-only AI keys used for analytics.

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](/ai/bring-your-own-ai) used to connect an assistant to your analytics and integration data.

<Warning>
  **Agent keys are not AI keys.** An [AI key](/ai/bring-your-own-ai) (`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."
</Warning>

## 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**:

<Steps>
  <Step title="New agent key">
    Click **New agent key**. Give it a label and choose the environment (**production** or **sandbox**).
  </Step>

  <Step title="Grant capabilities">
    Select which of the four tools this key may call. Leave `create_payment_link` unchecked to issue a read-only key.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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:

<CodeGroup>
  ```bash Claude Code theme={"dark"}
  claude mcp add --transport http therius-agent https://api.therius.io/v1/mcp \
    --header "Authorization: Bearer <your-agent-key>"
  ```

  ```json Claude Desktop / Cursor (mcp.json) theme={"dark"}
  {
    "mcpServers": {
      "therius-agent": {
        "url": "https://api.therius.io/v1/mcp",
        "headers": { "Authorization": "Bearer <your-agent-key>" }
      }
    }
  }
  ```
</CodeGroup>

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.

<Note>
  This is a separate endpoint from the [Bring Your Own AI](/ai/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.
</Note>

## Tools

| Tool                      | Does                                                                                                                                                 | Capability                | Mutating |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -------- |
| `create_payment_link`     | Creates a single-use, chargeable payment link for a shopper to pay. Checked and reserved against this key's spend limits before the link is created. | `create_payment_link`     | Yes      |
| `get_payment_link_status` | Looks up the status of a payment link this key created.                                                                                              | `get_payment_link_status` | No       |
| `list_payment_links`      | Lists this merchant's payment links, optionally filtered by status.                                                                                  | `list_payment_links`      | No       |
| `get_payment_status`      | Looks up the status of a payment by ID or payment code, scoped to this key's merchant.                                                               | `get_payment_status`      | No       |

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`.

### `create_payment_link` arguments

| Argument          | Type    | Required | Notes                                                                                                                      |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `amount`          | integer | Yes      | Minor units (e.g. cents). Checked against the key's per-link and remaining daily cap.                                      |
| `currency`        | string  | Yes      | ISO 4217 code. Must match the currency configured on the key's spend limits — a request in any other currency is rejected. |
| `title`           | string  | No       | Shown on the hosted checkout page.                                                                                         |
| `description`     | string  | No       | Shown on the hosted checkout page.                                                                                         |
| `reference`       | string  | No       | Your own order reference.                                                                                                  |
| `expires_in_days` | integer | No       | Defaults to 7.                                                                                                             |

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.