Authentication and limits

Tayho operators issue API keys on request. There is no public key-creation endpoint or end-user key management workflow in the MVP.

Key kinds

Publishable keys use the th_pk_ prefix. They may be embedded in a browser application only when the key has an exact origin allowlist and conservative quotas. A publishable key is an application identifier with policy—not a substitute for wallet authorization. Secret keys use the th_sk_ prefix and must remain on a trusted server. Never include one in a browser bundle, mobile binary, repository, documentation example, or client-visible log. Send either kind in a header:

X-API-Key: th_pk_example

The header is required for all /v1 REST operations. Realtime WebSockets use a single-use ticket derived from the key instead of sending the key during the upgrade.

Scopes

Scope	Grants
`read`	Indexed reads, live unsigned reads, simulation, and batch reads
`realtime`	Creation of short-lived WebSocket tickets
`actions:submit`	Relayed actions and intents, cancellations, lists, and protected receipt reads

Every generated REST operation shows x-tayho-required-scope and its quota class. A key with the wrong scope fails with 403; retrying the same key cannot fix it. Keys can also be restricted by deployment environment, browser origin, source CIDR, status, and expiry. Requests fail closed when a restriction cannot be satisfied.

Quota classes

Projects maintain separate per-minute budgets:

read for indexed reads;
live for RPC-backed calculations and action preparation reads;
realtime for new WebSocket connections; and
submit for relayed write intake and cancellation.

Admission is checked at project, key, and IP levels. Additional controls can limit wallet activity, pending actions, per-transaction sponsored gas, and daily sponsored gas. Your issued project configuration determines the actual values; there is no universal public numeric limit.

Rate-limit response

When admission rejects a request, expect HTTP 429 with:

Retry-After: 60
X-RateLimit-Limit: 120
X-RateLimit-Scope: project
X-Request-ID: request-12345678

Wait for at least Retry-After, add jitter, and avoid parallel retries. The limit header describes the rejecting budget, not necessarily every budget applied to the request. For signed writes, reuse the same prepared SDK object or the exact same body and idempotency key. For realtime, keep one shared subscription per application context and allow the SDK reconnect loop to create a fresh ticket.

Authentication failures

HTTP	Typical cause	Response
`401`	Invalid, expired, or revoked key	Obtain a valid active key
`403`	Suspended project, wrong scope, origin, CIDR, or environment	Correct the key policy or request origin
`429`	Project, key, IP, wallet, or action budget exhausted	Respect `Retry-After`
`503`	Authentication or admission dependency unavailable	Retry safe work with backoff

Include x-request-id, method, path template, status, and error code when requesting support. Never include the API key, receipt capability, wallet signature, or full signed payload.

​Authentication and limits

​Key kinds

​Scopes

​Quota classes

​Rate-limit response

​Authentication failures