# Agent self-signup

An AI agent mints its own capped trial key with POST /agent/signup, uses it without a human, and hands a claim link to its human when the trial budget runs out. The agent keeps the same key.

An agent that needs data should not have to stop and wait for someone to create an account. `POST /agent/signup` gives it a working key in one call, with a small budget of free credits that a person can later extend. No email, card or human step is involved.

`POST https://api.primaryapi.com/agent/signup`

Auth: None (rate limited per network)

## Mint a trial key

The body is optional; a `label` (up to 80 characters) helps the human recognise the key later.

```bash
curl -sS -X POST "https://api.primaryapi.com/agent/signup" \
  -H "Content-Type: application/json" \
  -d '{"label":"lead-research agent for acme.example"}'
```

```json title="201 Created (shortened)"
{
  "secret": "pa_live_…",
  "keyId": "key_01JBXM3T5V7Q9R2K4N6P8W0Y1Z",
  "expiresAt": "2026-11-06T14:05:09.120Z",
  "upgrade": {
    "claimUrl": "https://primaryapi.com/dashboard/authorize?claim=3f1c…",
    "authorizationServer": "https://api.primaryapi.com",
    "scope": "run balance:read"
  },
  "notice": "This is a free PrimaryAPI trial API key with … credits for API calls. It expires in 7 days (2026-11-06 14:05 UTC). No account was created and nothing is owed. To keep using it, a human can sign in and approve it at https://primaryapi.com/dashboard/authorize?claim=3f1c… — the agent keeps the same key."
}
```

| Field | Meaning |
|---|---|
| `secret` | The API key. Shown once. Store it as `PRIMARYAPI_API_KEY`. |
| `keyId` | The key's id, useful when the human manages it later. |
| `capCredits` | The trial budget, in credits (left out of the example above). |
| `expiresAt` | When the trial key stops working if nobody claims it (currently 7 days). |
| `upgrade.claimUrl` | The page where a human approves the key. Also returned with `trial_cap_reached`. |
| `notice` | A plain-language summary for the human. Relay it word for word. |

## Rules for agents

- **Never print, log or commit the secret.** Keep it in an environment variable or your secret store and send it only in the `Authorization` header.
- **Relay `notice` to your human**, unchanged, as soon as you have it.
- **Reuse the key.** One network can create 3 trial keys per 24 hours, and there is a daily limit across all agents. Past either limit, signup answers `429 rate_limited` with `retryAfterSeconds` and a message suggesting a regular account.
- **Check prices before spending.** `POST /v1/quote/{sku}` is free and shows what a call will cost, in credits.

## What a trial key can do

A trial key has `run` access: it can search the catalog, quote, run APIs, poll requests and re-read results, and send feedback. It cannot read the workspace's balance or usage, manage keys, or call [restricted APIs](/docs/restricted-apis). Calls are paid from the trial credits, under the same rules as any key: you pay only for answers, and a call is admitted only when the remaining trial credits cover the most it can cost (its quote's `maxCredits`). For per-result APIs, a smaller `limit` makes a call fit.

## When the budget runs out

The first call that does not fit the remaining budget answers `402 trial_cap_reached`, with the claim link in `upgrade`:

```json title="402 Payment Required"
{
  "code": "trial_cap_reached",
  "error": "this trial key has used its free allowance — ask a human to approve continued use at the link in upgrade.claimUrl",
  "requestId": "req_01JBXQ8N0R2T4W6Y8A0C2E4G6J",
  "upgrade": {
    "claimUrl": "https://primaryapi.com/dashboard/authorize?claim=3f1c…",
    "authorizationServer": "https://api.primaryapi.com",
    "scope": "run balance:read"
  }
}
```

Nothing was charged. Show `upgrade.claimUrl` to your human, explain what you need the data for, and wait. Do not create another trial key to get around the cap. After approval, retry the same call; if you sent an `Idempotency-Key`, reuse it: the earlier refusal does not hold the key.

## How a human claims the key

1. They open the claim link and sign in, or create an account.
2. They see a receipt of the trial: the key's label and prefix, the credits it spent out of its budget, how many calls it made and the most recent ones.
3. They choose a spend limit for the key in credits, for example 2,500 credits per month (daily, weekly or monthly), or no limit beyond the workspace's balance, and approve.

From that moment the key belongs to their account: the trial cap is gone, the chosen limit applies, and calls are paid from their workspace's credits. **The agent keeps the same secret**; nothing needs to be reconfigured. The human can later change the limit, rotate or revoke the key like any other key in the dashboard.

If the trial key has already expired, the claim link keeps working for 7 more days and approving it brings the key back. After that the link answers `404 not_found` and the agent should sign up again.

## Endpoints used by the claim page

The claim page uses two endpoints that only work with a signed-in browser session (never with an API key):

| Endpoint | Purpose |
|---|---|
| `GET /v1/agent/claim/{token}` | The receipt: label, key prefix, created and expiry times, credits spent and the cap, request count, recent calls, and whether it was already claimed. |
| `POST /v1/agent/claim/{token}/approve` | Approve with `{"limitCredits": 2500, "limitInterval": "monthly"}`, or `{"limitCredits": null}` for no limit. Answers with the key as it now is. Approving twice is harmless. |

## Through MCP

An agent connected to the [MCP server](/docs/mcp-server) can browse the catalog without any key. To run calls it needs a key in its MCP client configuration; the server's instructions point keyless agents to `POST /agent/signup`.
