App Credentials

How app credentials authenticate end-users, the session token flow, domain validation, and Proof-of-Work protection.

App credentials are the auth mechanism for chat components. This page covers the underlying auth flow, security model, and advanced configuration.

How Authentication Works

When your widget loads, it authenticates through a two-step flow:

Get a session token — the widget calls POST /run/auth/apps/{appId}/anonymous-session. The server validates the request Origin against the app's allowed domains and returns a JWT.
Use the token — subsequent chat requests include the JWT and App ID:
Authorization: Bearer <session_token> X-Inkeep-App-Id: <app_id>

Each session gets a unique anonymous user ID (anon_<uuid>), enabling per-user conversation history.

To refresh a token while preserving the same anonymous identity, include the existing token as an Authorization: Bearer header when requesting a new session. If the token is valid, the server reuses the same user ID (sub claim) and issues a fresh token with a new 30-day expiry. If the token is invalid, expired, or belongs to a different app, a new anonymous identity is created as usual.

Create an App via API

curl -X POST "https://your-api.example.com/manage/tenants/{tenantId}/projects/{projectId}/apps" \
  -H "Authorization: Bearer $MANAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Chat Widget",
    "type": "web_client",
    "defaultAgentId": "your-agent-id",
    "config": {
      "type": "web_client",
      "webClient": {
        "allowedDomains": ["docs.example.com"]
      }
    }
  }'

See the Apps API Reference for the full CRUD API.

Proof-of-Work Protection

When Proof-of-Work (PoW) is enabled on the server, clients must solve a computational challenge before requesting a session token. This protects against automated abuse.

Note

PoW is optional and controlled by the server administrator via the INKEEP_POW_HMAC_SECRET environment variable. If PoW is not enabled, the challenge endpoint returns 404 and clients skip this step.

Client Integration

Install the solver library:

npm install altcha-lib

Fetch a challenge, solve it, and include the solution when requesting a session token:

import { solveChallenge } from "altcha-lib";

const BASE_URL = "https://your-api.example.com";

async function getPowHeaders(): Promise<Record<string, string>> {
  const res = await fetch(`${BASE_URL}/run/auth/pow/challenge`);

  if (res.status === 404) {
    return {}; // PoW not enabled — skip
  }

  const challenge = await res.json();
  const { promise } = solveChallenge(
    challenge.challenge,
    challenge.salt,
    challenge.algorithm,
    challenge.maxnumber,
  );
  const solution = await promise;

  const payload = btoa(JSON.stringify({
    algorithm: challenge.algorithm,
    challenge: challenge.challenge,
    number: solution?.number,
    salt: challenge.salt,
    signature: challenge.signature,
  }));

  return { "X-Inkeep-Challenge-Solution": payload };
}

Include the returned headers in the anonymous session request:

const powHeaders = await getPowHeaders();

// To refresh an existing session and preserve identity,
// include the current token in the Authorization header.
const existingToken = getStoredToken(); // your token storage logic

const response = await fetch(`${BASE_URL}/run/auth/apps/${APP_ID}/anonymous-session`, {
  method: "POST",
  headers: {
    ...powHeaders,
    ...(existingToken ? { Authorization: `Bearer ${existingToken}` } : {}),
  },
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error?.message || "Session request failed");
}

const { token } = await response.json();

Security Model

Feature	Details
Domain allowlist	`Origin` header validated against the app's `allowedDomains` at token issuance
Scoped access	Each app is bound to a default agent via `defaultAgentId`
Anonymous identity	Each session gets a unique user ID for per-user conversation history
Token expiry	Session tokens have a configurable TTL (default: 30 days)
PoW	Optional Proof-of-Work challenges prevent automated abuse
Rolling refresh	Include existing token when requesting a new session to preserve identity with a fresh expiry

App Credentials vs API Keys

	App Credentials	API Keys
Use case	Browser / client-side	Server-to-server
Exposed to end-users	Yes (App ID only)	No (secret)
Domain restrictions	Yes	No
Per-user identity	Yes (anonymous sessions)	No
Default agent	One agent (via `defaultAgentId`)	One agent per key

Chat Components — widget setup and configuration
Chat API — low-level streaming API details
Apps API Reference — CRUD operations for app management
Auth API Reference — session and PoW challenge endpoints