---
title: "Mint a trial API key — no account, no host, no signature"
method: POST
path: "/api/v1/agent-key"
tags: ["Credentials"]
---

# Mint a trial API key — no account, no host, no signature

`POST /api/v1/agent-key`

## Request

- Base URL: `https://data.useplinth.com`
- URL: `https://data.useplinth.com/api/v1/agent-key`
- Auth: none required

Mints a short-lived, read-only evaluation key. No account, no card, no browser, and nothing created in anyone else's name.

**The ordinary route needs no credential of any kind.** POST here with `purpose` and `source` and you get a key immediately — but LOCKED: it may make only the calls its challenge names. Make them, read the fields the questions ask about, POST those values to `/api/v1/agent-key/answer`, and the key unlocks for general use. When that budget is spent, take another challenge. As often as you like, free.

Every fiscal year in the corpus is readable; what is small is the row cap and the per-challenge budget, both announced in `x_plinth.warnings` at `caveat` severity.

**Signing is the alternative, not the requirement.** A caller that can publish an Ed25519 key directory and sign per RFC 9421 (Web Bot Auth profile: cover `@authority` and `signature-agent`, tag `web-bot-auth`, with `created`, `expires`, a `nonce` and a `keyid` that is the base64url JWK SHA-256 thumbprint) is issued at a higher tier with a larger budget and no challenges. That allowance IS a total and never refills. GET this path for the full ladder.

## Headers

- `Signature-Agent` string
- `Signature-Input` string
- `Signature` string

## Request body

- AgentKeyRequest
  - `purpose` string, required: What you are evaluating. Recorded, never verified, never gates — but required.
  - `source` string, required: Who or what is calling: an agent name, product or host. Recorded, unverified, required.
  - `contact` string: Optional. A URL or address we can reach you at.

## Response `201`

A trial key, its expiry, its budget, and the challenge it arrives locked to.

- TrialKey
  - `code` integer, required
  - `message` string
  - `key` string, required: The credential. Send as X-API-Key.
  - `key_prefix` string
  - `plan` string
  - `tier` string, required
  - `tier_label` string
  - `expires_at` string, date-time, required
  - `calls_ceiling` integer
  - `calls_used` integer
  - `calls_remaining` integer
  - `budget_is` string
  - `max_limit` integer
  - `max_page` integer, nullable
  - `scope` string
  - `challenge` object: Present when the key arrives LOCKED. Until these are answered the key may make only the calls named here.
    - `questions` ChallengeQuestion[]
      - `call` string, required: The exact request to make, method and URL.
      - `ask` string, required: What to read out of that response, in plain English.
    - `answer_at` string
    - `attempts` string: How many answers this challenge takes and how they are spaced. Running out draws a FRESH challenge rather than locking the key.
  - `terms` object: What is enforced, and what we ask of you.

## Other responses

- `400`: `purpose` or `source` missing or too short.
- `401`: A signature was presented and did not verify, or was replayed. The body says which.
- `429`: This signature-agent host has minted its allowance of trial keys today.
- `502`: Your key directory could not be read — your signature may be fine.
- `503`: Trial keys are at capacity; get a free key with an account instead.

---

[API](https://skmtc.dev/useplinth/apis/plinth-grants-api.md) · [All operations](https://skmtc.dev/useplinth/apis/plinth-grants-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useplinth/apis/plinth-grants-api/revisions/15273cd72ecf?raw)