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 { SignJWT, importPKCS8 } from 'jose';
import { auth } from '../lib/auth'; // your auth library

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 with your auth system
  const session = await auth.api.getSession();

  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

Enforcing authentication

New apps require authenticated sessions by default. If a signed JWT is missing or verification fails, the request is rejected with a 401 Unauthorized response.

To allow anonymous sessions (e.g., for public-facing widgets that don't require user identity), disable Require Authentication in the app edit dialog. When disabled, requests without a valid JWT fall back to anonymous authentication instead of being rejected.

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

Manage public keys from the app edit dialog in the Visual Builder. Navigate to Apps → click the ⋯ menu on your Web Client app → Edit, then scroll to the Authentication Keys section.

From here you can add, view, copy, and delete public keys. Each key requires:

Below the keys section, the Audience (aud) field lets you require that signed JWTs include a matching aud claim. When set, tokens without a matching audience are rejected. See Enforcing authentication for the Require Authentication toggle.

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