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.