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.

apiConfig = {
  // Public key (pk_v1_...) — safe to ship in client bundles
  apiKey: "pk_v1_your_public_key",
  endpoint: "https://api.ai-autocomplete.com/api/suggest",
  headers: { "X-Tenant": "acme" },
};

// <ai-autocomplete [apiConfig]="apiConfig" (submitted)="onSubmit($event)" />

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.
apiConfig = {
  type: "accessToken" as const,
  getAccessToken: async () => {
    const res = await fetch("/api/ac-token");
    const { access_token, expires_at } = await res.json();
    return { accessToken: access_token, expiresAt: expires_at };
  },
};

// <ai-autocomplete [apiConfig]="apiConfig" (submitted)="onSubmit($event)" />