Authentication

All API endpoints require authentication via API key. This page covers key formats, rate limiting, and the credit unit billing system.

API Key Format

Keys are prefixed by environment to prevent accidental cross-environment usage:

Environment	Prefix	Usage
Development	`shroud_dev_`	Local testing and development
Staging	`shroud_stage_`	Pre-production testing
Production	`shroud_prod_`	Production workloads

Requests with a key for the wrong environment are rejected with HTTP 401 Unauthorized.

Using Your Key

Include the key in the Authorization header on every request:

Authorization: Bearer shroud_prod_your_key_here

This applies to all protocols: JSON-RPC, MCP, OpenAI-compatible API, RPC Proxy, and Cocoon WebSocket.

Obtaining Keys

API keys are managed through:

Shroud Dashboard — open API Keys in the sidebar to create, revoke, and manage keys
Telegram Mini App — use @compute_for_all_bot to generate keys directly in Telegram

Each key belongs to a workspace and inherits the workspace's plan limits.

Header format

The gateway requires the exact prefix Bearer (capital B, single space) followed by the raw key. Anything else returns 401 Unauthorized with {"error_code": "SHROUD_UNAUTHORIZED"}.

Header value	Result
`Authorization: Bearer shroud_prod_...`	Accepted
`Authorization: shroud_prod_...`	Rejected — missing `Bearer` prefix
`Authorization: Token shroud_prod_...`	Rejected — wrong scheme
`Authorization: bearer shroud_prod_...`	Rejected — case-sensitive
`X-API-Key: shroud_prod_...`	Rejected — wrong header

If your HTTP client lets you set the auth scheme separately from the token (for example requests.auth.HTTPBearerAuth or axios' Authorization shorthand), confirm it emits the literal Bearer prefix and not a lowercase or alternative scheme.

Rate Limiting

API requests are subject to per-key rate limiting based on your plan:

Plan	RPS	Included CU / month	Overage	Price
Free	2	10,000,000	Not available	$0/mo
Developer	10	29,000,000	29/mo
Startup	50	99,000,000	99/mo
Enterprise	200	499,000,000	499/mo

When the rate limit is exceeded, the server responds with HTTP 429 Too Many Requests and a Retry-After: 1 header.

Credit Units (CU)

Each API call consumes Credit Units. The fixed exchange rate is 1 USD = 1,000,000 CU (tracked internally as milli-CU, where 1 CU = 1,000 milli-CU). Two pricing tracks feed the bill:

AI inference (Cocoon) — derived per call from a per-token price published on the TON blockchain and the live TON/USD rate.
RPC / MCP tools — fixed per-method CU cost from the gateway whitelist.

CU consumption is reported in _meta.usedCUMilli (MCP), result.usedCUMilli (JSON-RPC), or the top-level usedCUMilli field on the Cocoon done message.

For the formula, a worked example, the per-1M-token tier-pricing calculation, and the CU-limit response shape, see Billing & Credit Units.

CU limits per key

Each key can carry its own rolling CU limits in addition to the plan-level cap:

24-hour limit — maximum CU in a rolling 24-hour window.
30-day limit — maximum CU in a rolling 30-day window.

When a limit is exceeded the server responds with HTTP 429 and a cu_limit_exceeded body — see Billing — CU-limit responses.

Payment Methods

Shroud supports multiple payment methods. Top-ups land in the same workspace balance regardless of source.

Stripe — credit card payments.
TON — cryptocurrency payments via TON wallet.
Telegram Stars — payments through Telegram Mini App.

The dashboard's Usage Analytics view shows the running balance, the included-vs-overage split for the month-to-date, and a per-tool breakdown.

Last modified: 08 May 2026