Service

SERVICE ONLY: issue a free read-only key for a Telegram user

Not for integrators. Called by the PublicAML Telegram bot (@PublicAMLbot) to hand its users a free read-only API key.

Only an allowlisted key-issuing service may call it, with an HMAC-signed request. Everyone else gets 403 key_issuer_required: anonymous callers, bare X-API-Key requests (including the service's own key sent unsigned) and signed requests from any other customer.

What is issued is fixed server-side: tier free, no HMAC secret (the key is sent bare as X-API-Key and can only read), the free-tier quota in units per window_sec, a tg_ prefix, and customer_id = tg-<telegram_user_id>.

Idempotent per external_id: an active key is returned again with reissued: true and status 200. A revoked or expired key is 409 key_revoked and no new key is minted. New keys are capped per rolling 24 hours across the whole endpoint (429 daily_issue_limit); returning an existing key is never capped.

create: false only looks: it returns the user's key (200) or 404 no_key, never mints one, and neither spends nor is limited by the daily budget. It is what the bot's /mykey uses.

200 and 201 carry usage: the key's quota spend in the current rate-limit window (the same counter as its RateLimit-* headers), plus 24 h and 30 d totals, or null when that could not be read.

post/v1/service/free-keys

Request

  • Base URL: https://intelapi.publicaml.org
  • URL: https://intelapi.publicaml.org/v1/service/free-keys
  • Auth: API key in header X-Signature and API key in header X-API-Key and API key in header X-Timestamp

Request body

external_idstring required

tg:<telegram_user_id>. Decides the customer id (tg-<id>) one-to-one.

displaystring

Optional human-readable name. Written to the service log next to the key fingerprint; not stored with the key and never returned.

createboolean

false = look up only: return the existing key or 404 no_key, never create one. Must be a JSON boolean.

Response

The user already holds an active key; it is returned again (reissued: true).

api_keystring required

tg_…. Send it as X-API-Key on every call; it has no secret and cannot sign.

key_hintstring

16-hex fingerprint, safe to log. The same id usage accounting groups by.

customer_idstring

tg-<telegram_user_id>.

external_idstring
tier'free' | 'pro' | 'enterprise' required
hmacfalse
rate_limit_unitsinteger nullable required

Units (addresses) this key may spend per window_sec, metered per key across every endpoint. null = unmetered.

window_secinteger required

Rate-limit window in seconds (3600 in production).

created_atstring date-time required
reissuedboolean required

true when an existing active key was returned instead of a new one.

Changes

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