App Credentials

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

How anonymous authentication works

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

1. 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.
2. 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.

Authenticated chat sessions

In addition to anonymous sessions, apps can be configured for authenticated chat sessions. Your backend signs JWTs with a private key, and Inkeep verifies them using the corresponding public key you upload. This gives each session a verified user identity tied to your system's user IDs.

How it works

import { Router } from 'express';
import { fromNodeHeaders } from 'better-auth/node';
import { SignJWT, importPKCS8 } from 'jose';
import { auth } from '../lib/auth'; // your BetterAuth instance

const router = Router();

const PRIVATE_KEY_PEM = process.env.INKEEP_SIGNING_KEY!;
const KEY_ID = process.env.INKEEP_KEY_ID!; // matches the kid uploaded to Inkeep

router.post('/api/inkeep-token', async (req, res) => {
  // Verify the user's session via BetterAuth
  const session = await auth.api.getSession({
    headers: fromNodeHeaders(req.headers),
  });

  if (!session) {
    return res.status(401).json({ error: 'Not authenticated' });
  }

  const now = Math.floor(Date.now() / 1000);
  const privateKey = await importPKCS8(PRIVATE_KEY_PEM, 'RS256');

  const token = await new SignJWT({
    sub: session.user.id,      // becomes the userId in Inkeep
    email: session.user.email, // optional — available as a verified claim
  })
    .setProtectedHeader({ alg: 'RS256', kid: KEY_ID })
    .setIssuedAt(now)
    .setExpirationTime(now + 3600) // 1 hour
    .sign(privateKey);

  return res.json({ token });
});

export default router;

JWT requirements

Supported algorithms

Dual-mode support

Apps with auth keys still serve anonymous sessions by default. If a signed JWT verification fails, the request falls back to anonymous authentication. To require authenticated sessions only, set allowAnonymous to false in the app's auth configuration.

Verified claims

Non-standard claims in the signed JWT (beyond sub, iat, exp, aud, iss, jti, nbf) are extracted and made available as verified claims in the conversation context. These are cryptographically signed and kept separate from unverified userProperties sent by the client.

Key management API

Manage public keys for an app using the following endpoints:

Example — add a public key:

curl -X POST "https://your-api.example.com/manage/tenants/{tenantId}/projects/{projectId}/apps/{appId}/auth-keys" \
  -H "Authorization: Bearer $MANAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": "my-key-1",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBI...",
    "algorithm": "RS256"
  }'

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",
    "prompt": "Be concise and link to documentation pages when possible.",
    "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.

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

App Credentials vs API Keys

Related

• 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