Authentication

All API keys follow a consistent format: a jsk_live_ prefix followed by exactly 32 hexadecimal characters (0-9, a-f). This gives you a 128-bit key with sufficient entropy for secure authentication.

Example key: jsk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

• Prefix: jsk_live_ — identifies the key as a Jiro API key
• Body: 32 hex characters — the unique, randomly generated key material
• Total length: 40 characters

Keys are passed via the Authorization header using the standard Bearer scheme. You can also use the X-API-Key header as an alternative.

API keys are generated when you create an account or via the dashboard.

Self-hosted: When authentication is enabled, generate keys using the CLI:

bash # Generate a new API key jiro keys generate

# List all keys jiro keys list

# Revoke a key jiro keys revoke <key-id>

Cloud: Visit the Jiro dashboard at searchjiro.vercel.app, sign up for the waitlist, and generate your first key from the API Keys page. You receive 1,000 free credits immediately.

Each key is associated with a user record that tracks your plan type, role, credit balance, and banned status. You can create multiple keys for different environments (development, staging, production).

When you send a request to any Jiro API endpoint, the server performs a 6-step validation:

1. 1Extract token — the server extracts the Bearer token from the Authorization header (or X-API-Key header)
2. 2Verify prefix — it checks that the token starts with jsk_live_ and is exactly 40 characters long
3. 3Hash the key — it computes a SHA-256 hash of the raw key string. Only the hash is stored in the database — your raw key is never persisted on the server
4. 4Redis lookup — it looks up apikey:<hash> in Redis for fast retrieval. If not cached, it falls back to the database
5. 5Load user record — it retrieves the associated user record containing your plan type, role, credit balance, and banned status
6. 6Reject if invalid — the request is rejected with a 401 (INVALID_API_KEY) if the key is not found, or 403 (KEY_DISABLED) if the user account is banned

This flow ensures that even if the database is compromised, attackers only get SHA-256 hashes — not your raw API keys.

Never expose keys in client-side code. All API requests must go through your backend server. Exposing your API key in browser JavaScript, mobile apps, or any client-side code allows anyone to make authenticated requests on your behalf.

Use environment variables. Store keys in .env files or environment variables, never in source code:

bash # .env file (add to .gitignore) JIRO_API_KEY=jsk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Rotate keys regularly. You can revoke old keys and create new ones via the CLI or dashboard. This limits the damage window if a key is accidentally exposed.

Use separate keys for each environment. Create different keys for development, staging, and production. This makes it easy to revoke a compromised key without affecting other environments.

Monitor usage via the Credits endpoint. Check your credit balance and transaction history regularly to detect unauthorized use. Sudden spikes in credit consumption may indicate a compromised key.

Never commit keys to version control. Add .env files to .gitignore and use git-secrets or similar tools to prevent accidental commits.

Two error codes relate to authentication failures:

Each SDK handles authentication automatically. Just pass your API key to the client constructor: