# 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

```javascript
// 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](https://zalmir.ai/account) and restart the connection.

## 2. Exchange the code

```javascript
// 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](https://zalmir.ai/account/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.

Source page: https://zalmir.ai/docs/guides/oauth
