API — Authorization Premium

How to authenticate, how fast you can call, and what request rules every client must follow.

API Tokens

Every API request must include a Bearer token in the Authorization header. The token is a 64-character string prefixed with mok_, issued automatically when your server activates Mokito Premium.

Token format

mok_<60 random characters from [a-zA-Z-]>

Example token (do not use this — it is fake):

mok_aBcDeFgHiJkLmNoPqRsTuVwXyZ-exampleTokenForDocsOnly-xYzAbCdEfGh

Authorization Header

Authorization: Bearer mok_yourTokenHere

Keep your token secret. The raw token is shown to you only once when it is generated or regenerated. Store it securely. Only the SHA-256 hash of the token is stored in the Mokito database — no one can recover the raw token after the page is closed. If your token is compromised, regenerate it from the Steam Links page in your guild dashboard.

Auth Failure Responses

Scenario	Status	Response
Missing or malformed `Authorization` header	401	`{ "message": "Missing or malformed Authorization header. Expected: Bearer mok_..." }`
Token not found in the database (invalid / revoked)	401	`{ "message": "Invalid API token." }`
Token is valid but Premium has expired	403	`{ "message": "Mokito Premium subscription is expired or inactive for this server." }`

On a 401, the response includes a WWW-Authenticate: Bearer realm="mokito-api" challenge header.

Rate Limiting

The API enforces a per-token rate limit. The limit is keyed on the authenticated token's hash (not on the raw token and not on the client IP), so every API consumer has their own budget.

Limit	Value	Description
Fixed window	100 requests / 60 seconds	At most 100 requests per rolling one-minute window per token.

Response Headers

Header	Example	Meaning
`X-RateLimit-Limit`	`100`	Max requests per window.
`X-RateLimit-Remaining`	`72`	Requests remaining in the current window.
`X-RateLimit-Window`	`60s`	Window duration in seconds.

Exceeding the Limit

Exceeding the fixed-window limit triggers a ban: the token is blocked for a random duration between 15 and 30 minutes. Every request during the ban returns 429 Too Many Requests with retry metadata:

{
  "message": "Rate limit exceeded. You are being timed out for 22 minutes.",
  "retry_after_seconds": 1320,
  "retry_after_minutes": 22,
  "reset_at": "2026-06-20T15:30:00+00:00"
}

The 429 response also includes a standard Retry-After header (seconds until reset).

Ban duration is random. The ban is intentionally randomized (15–30 min) so a client cannot predict the exact reset time. The ban is cached with a matching TTL, so it expires automatically even if the server restarts.

Content Type

All request bodies (when present) must use Content-Type: application/json. Sending a body with any other content type returns 415 Unsupported Media Type:

{
  "message": "Unsupported media type. All request bodies must have a Content-Type of application/json.",
  "received_content_type": "application/x-www-form-urlencoded"
}

GET requests with no body pass through untouched — no Content-Type is required.

Security Headers

Every API response, success or error, includes these security headers:

Header	Value
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`Referrer-Policy`	`no-referrer`
`Cache-Control`	`no-store, no-cache, must-revalidate, private`
`Strict-Transport-Security`	`max-age=31536000; includeSubDomains` (HTTPS only)