Authentication

Authenticate every request to /v1/* by passing your secret key in the Authorization HTTP header:

Authorization: Bearer sk_mouse_...

Key format and pre-database checksum

Every production Mouse API key has a deterministic 58-character structure:

sk_mouse_<43 base62 random characters><6 base62 CRC32 checksum characters>

• Prefix (sk_mouse_): 9-character fixed prefix for secret scanners and log redaction filters.
• Random body (43 base62 chars): 256 bits (32 bytes) of cryptographic randomness encoded in base62 (0-9A-Za-z).
• Checksum (6 base62 chars): Fixed-width base62 encoding of CRC32(body).

Before performing any database lookup, the API verifies the prefix, length, and CRC32 checksum in constant time (secrets.compare_digest). Malformed keys, truncated strings, and scanner false positives are rejected immediately with 401 invalid_api_key without touching Postgres.

Storage and revocation

• Shown once: Raw keys are returned once at creation time in the API Keys console and never stored in plaintext.
• SHA-256 hashed: Only the SHA-256 digest of the key and a 13-character display prefix (sk_mouse_xxxx…) are stored in api_keys.
• Revocation TTL: Validated keys are cached in worker memory for up to 30 seconds. Revoking a key in the console or crossing a $0.00 credit balance takes effect across all workers within 30 seconds.
• GitHub secret scanning: If a sk_mouse_ key with a valid CRC32 checksum is committed to a public GitHub repository, Mouse automatically revokes the key and emails the account owner.

Key types

Key type	Where created	Rate limit	CORS / Browser access	Expiry
standard	Console → API keys	200 RPS (burst 400), 20M TPM	Server-to-server only (no browser CORS header)	Until revoked
playground	Minted automatically by Console Playground	5 RPS	Allowed from https://www.mouse.dev and https://mouse.dev	1 hour

Standard keys deliberately omit Access-Control-Allow-Origin on 200 responses so production keys cannot be used directly from browser client code. Keep MOUSE_API_KEY on your server or edge worker.

Authentication errors

HTTP status	error.type	error.code	Cause
401 Unauthorized	authentication_error	missing_api_key	Missing Authorization header or missing Bearer prefix.
401 Unauthorized	authentication_error	invalid_api_key	Key does not start with sk_mouse_, fails CRC32 checksum, is expired, or has been revoked.
402 Payment Required	billing_error	insufficient_credits	Key is valid, but the account's prepaid credit balance is $0.00. Top up at /console/billing.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "This API key is not valid. Check it or create a new one."
  }
}