Skip to content
Zalmir Beta

OAuth PKCE

Let users choose to give your app its own Zalmir API key. They sign in on Zalmir, see your exact callback origin, optionally set a lifetime credit limit, and approve. Requests made with the key spend the user's credits.

1. Send the user to Zalmir

// Run in your app. Keep the verifier private to this connection attempt.
const base64url = bytes => btoa(String.fromCharCode(...bytes))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(new Uint8Array(await crypto.subtle.digest(
  'SHA-256', new TextEncoder().encode(verifier))));
const state = base64url(crypto.getRandomValues(new Uint8Array(24)));
// Save { verifier, state } in your session, bound to this attempt.
const callback = new URL('https://your-app.example/callback');
callback.searchParams.set('state', state);
const query = new URLSearchParams({ callback_url: callback.href,
  code_challenge: challenge, code_challenge_method: 'S256' });
location.assign('https://zalmir.ai/auth?' + query);

Use an HTTPS callback. For local development, HTTP is allowed only for localhost or 127.0.0.1, on any port. URLs with credentials or fragments, and non-HTTP(S) schemes, are refused. Put your own unpredictable state inside the callback query; Zalmir preserves that query and replaces any existing code.

A challenge is required. Use a cryptographically random 43–128 character verifier containing only letters, digits, -._~. S256 challenges are the unpadded base64url SHA-256 of that verifier (43 characters). The method defaults to S256. The person signing in needs an active Zalmir account; if theirs still needs setting up, they can finish it in Account and restart the connection.

2. Exchange the code

// In your app's callback: verify state against the saved session first.
const callback = new URL(location.href);
// savedVerifier is the verifier for THIS validated state/connection attempt.
const response = await fetch('https://zalmir.ai/api/v1/auth/keys', {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code: callback.searchParams.get('code'),
    code_verifier: savedVerifier, code_challenge_method: 'S256' })
});
if (!response.ok) throw new Error('Connection failed; start again');
const { key } = await response.json();
// Store the key securely. Do not log it or put it in a URL.
// Remove the code from your callback URL and discard the saved verifier.

Success is {"key":"zal_…"}. No sign-in cookie, existing API key, or client secret is required for this exchange. Browser apps can use CORS without credentials. JSON bodies are limited to 4 KiB. The credential is returned only on that successful exchange; a retry never retrieves it.

Codes expire after five minutes and can be exchanged once. They are bound to the approving account, callback, and challenge method. A wrong verifier or method, an unknown, expired, used, or attempt-exhausted code, and an inactive account all return the same 400 error. A code permits at most five verification attempts. The exchange allows 30 attempts per minute per trusted client-address bucket, shared across site instances; without a trusted address, callers share an unattested bucket. An IP refusal returns 429 with Retry-After: 60. A service failure returns 503.

3. User control

The new inference key is named App: <callback host[:port]> (up to 64 characters) and appears in API keys. Users can rename, disable, rotate, limit, or revoke it like any other key. A blank consent limit adds no key-specific cap; requests are still bounded by available credits. A selected limit is enforced by the existing per-key lifetime spending limit. Existing account key-issuance throttles also apply; if issuance is refused, the exchange returns the generic code error.

Compatibility and security

The plain method works too: use the verifier itself as the challenge and set code_challenge_method: "plain" at both stages. Prefer S256. Zalmir always requires PKCE. Headless/no-callback connections, custom key labels, and app marketplace attribution are not implemented.

Consent requires an explicit same-origin POST and a freshly verified session; opening the page never issues a code. The page cannot be framed. Cancel returns to the Console without contacting the callback. Codes and key credentials are stored only as hashes. The API key is a bearer credential: your app can make API calls until the key is revoked or otherwise refused. No prompts or answers are part of this authorization flow.