Credentials

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

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.

post/api/v1/agent-key

Request

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

Headers

Signature-Agentstring

The https origin publishing your key directory, as a structured-field string: "https://your-host.example".

Signature-Inputstring

RFC 9421 covered components and parameters, e.g. sig=("@authority" "signature-agent");created=…;expires=…;keyid="…";alg="ed25519";nonce="…";tag="web-bot-auth"

Signaturestring

sig=:<base64 ed25519 signature>: Send all three signature headers or none.

Request body

purposestring required

What you are evaluating. Recorded, never verified, never gates — but required.

sourcestring required

Who or what is calling: an agent name, product or host. Recorded, unverified, required.

contactstring

Optional. A URL or address we can reach you at.

Example request

{
  "purpose": "Evaluating grant-graph coverage for a funder-research tool",
  "source": "acme-research-agent/1.0"
}

Response

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

codeinteger required
messagestring
keystring required

The credential. Send as X-API-Key.

key_prefixstring
planstring
tierstring required
tier_labelstring
expires_atstring date-time required
calls_ceilinginteger
calls_usedinteger
calls_remaininginteger
budget_isstring
max_limitinteger
max_pageinteger nullable
scopestring
termsobject

What is enforced, and what we ask of you.

Changes

No recorded changes to this operation across all 1 revision of this API.