Authentication

Choosing a mode

Public key mode is the fastest path: drop a public key into apiConfig and you're done. Secret key + access token mode is what we recommend for production — your server keeps the secret key, mints short-lived access tokens, and the SDK handles refresh transparently.

Public key mode

Use a public key when calling the SDK directly from the browser. Public keys are scoped, rate-limited, and safe to ship in client-side bundles. This is the fastest path to a working integration.

new AIAutocomplete(container, {
  apiConfig: {
    // Public key (pk_v1_...) — safe in client bundles
    apiKey: "pk_v1_your_public_key",
    endpoint: "https://api.ai-autocomplete.com/api/suggest",
    headers: { "X-Custom": "v" },
  },
  onSubmit: handleSubmit,
});

Secret key + access token (recommended)

Keep your secret key on your backend server. The server — never the browser — exchanges it for a short-lived access token. Your frontend fetches the token from your own backend route, then hands it to the SDK via getAccessToken. The SDK handles refresh, retries, and concurrency dedupe — the secret key never reaches the browser.

On your server

On your backend, expose a route that exchanges your secret key for a short-lived access token by calling the endpoint below. Forward the response to the browser; the SDK reads it through getAccessToken. The secret key must never reach the browser — keep it in a server-side environment variable with no client-side prefix.

{
  "product_id": "<uuid>"
}

{
  "access_token": "at_v1_AbCdEfGh...",
  "expires_at": 1775464738,
  "token_type": "Bearer"
}

{
  "error": {
    "code": "INVALID_SECRET_KEY",
    "message": "The provided secret key is invalid"
  }
}

In the browser

The frontend SDK calls a route on your own backend (e.g. /api/ac-token), reads the access token + expiry, and returns them to the SDK. No secret-key code lives here.

// BROWSER-ONLY. No secret key here — only the URL of your own
// backend route, which holds the secret key.
new AIAutocomplete(container, {
  apiConfig: {
    type: "accessToken",
    getAccessToken: async () => {
      const res = await fetch("/api/ac-token");
      const { access_token, expires_at } = await res.json();
      return { accessToken: access_token, expiresAt: expires_at };
    },
    endpoint: "https://api.ai-autocomplete.com/api/suggest",
  },
  onSubmit: handleSubmit,
});