Guide
Authentication and keys
Sessions, personal API keys, scopes, limits and how keys are kept safe.
Two ways in
| Caller | How |
|---|---|
| The Jutsu web app | A signed-in session cookie (HttpOnly, SameSite=Lax). Writes must come from the same origin. |
| Your scripts, bots and tools | A personal API key: Authorization: Bearer jts_<prefix>_<secret> |
Third-party apps acting for other players will use OAuth with the same scopes (planned).
Keys
- Created from a signed-in session only (a key cannot mint more keys).
- Shown once. We store only a SHA-256 hash of the secret and compare in constant time.
- Up to 10 active keys, optional expiry (up to 365 days), revocable instantly.
lastUsedAtis updated at most once a minute.- Every key creation and revocation is in your security log (
GET /me/audit).
Scopes
GET /scopes lists them all. Sensitive scopes can move money or ownership and must be picked
explicitly: approvals:write, finance:write, market:write, ownership:write.
A call without the scope it needs fails with 403 insufficient_scope and names the missing scopes.
Limits
Requests are limited per key or user (300 per minute for keys, 600 for sessions) and per operation for
sensitive ones (shown as x-rate-limit in the reference). Over the limit you get 429 rate_limited.