Authentication

Connect your application's authenticated users to chat with short-lived tenant JWTs. Your server signs them with an organization API key. The browser receives only the token. Any backend language and session system can provide this endpoint.

The auth token endpoint

Expose POST /api/astralbeam/token on your backend. Authenticate the request, derive user and customer-account IDs from the session, and return { token } with Cache-Control: no-store. Keep your framework's session and CSRF protections.

The Quickstart has TypeScript and Rails handlers. With the JavaScript SDK, sign the session identity like this:

ts
import { createAstralBeamToken } from "@astralbeam/sdk/server"

const token = await createAstralBeamToken({
  apiKey: process.env.ASTRALBEAM_API_KEY!,
  user: { id: session.user.id },
  tenant: { id: session.tenant.id },
})

Never accept these IDs from the request body. Return an authentication error for a missing session and keep signing errors private.

Where the token comes from

Chat calls /api/astralbeam/token by default. Set fetchAstralBeamToken for another endpoint or custom authentication:

Endpoint
<AstralBeamChat
  fetchAstralBeamToken={{
    url: "https://api.acme.com/api/astralbeam/token",
    headers: { Authorization: `Bearer ${accessToken}` },
  }}
/>

Endpoint requests default to POST, credentials: "include", cache: "no-store", and JSON responses. Standard RequestInit options override them. Keep CSRF headers when your backend requires them.

Directories require an explicit token source. Both forms synchronize /me and renew tokens automatically. Returning undefined or throwing blocks authenticated work and offers retry.

Cross-origin endpoints must allow your application's origin, required headers, and OPTIONS preflight. Cookie-based requests also need credentialed CORS.

Switching workspaces

Remount chat when the signed-in user or Tenant changes. Updating a token callback alone takes effect only on the next acquisition:

tsx
<AstralBeamChat key={`${session.tenant.id}:${session.user.id}`} />

Update your trusted server session before rendering the new identity. The token endpoint must check membership in the selected Tenant, and every host tool must enforce the same scope. Clearing the transcript alone does not establish a new identity.

Linearity demonstrates remounting across two mock workspaces. Its demo identity policy is not suitable for production.

Directory access

Verify customer-admin permissions on your backend before signing user.admin: true. This grants reading the Tenant and reading and writing its TenantUsers. A read-only widget does not reduce token authority, and the stored admin field grants none.

The SDK synchronizes the signed Tenant and current TenantUser through /me. Other users appear after their own synchronization or a management API import. Deleting a TenantUser does not revoke its token: a later synchronization recreates it. See Directories.

Usage limits

Default usage limits apply automatically. Add plan-specific IDs with usageLimits. These apply alongside the defaults. See Usage limits.

ts
const token = await createAstralBeamToken({ apiKey, user, tenant, usageLimits: planLimits[plan] })

Troubleshooting

  • For a disabled composer, check the token endpoint and retry. apiUrl must point to the deployment that issued your API key.
  • For a revoked or expired key, create a replacement under API Keys and deploy it to your backend. New tokens signed with the old key cannot restore access.
  • Use widget debug logging or headless streamCallbacks.onError to distinguish host endpoint failures from rejected AstralBeam tokens.
  • For CORS errors, check headers on failure responses as well as successful ones.

Refresh and current-user behavior

Authentication is ready after token acquisition and /me succeed. While visible and online, the SDK renews tokens before expiry and resynchronizes stale identity on focus or reconnect. A 401 triggers one renewal and retry. Temporary synchronization failures retry with backoff and respect Retry-After.

Failed synchronization hides the cached identity and blocks new work. An already-authorized stream can continue. Changes to the token callback apply on the next acquisition, so remount for account changes.

Synchronization preserves omitted profile fields, while supplied metadata replaces the whole object. Always mint tokens from current host data because an older token can overwrite newer profile values. See the current-user API for update rules.

Rules

Treat the token as a session credential. Keep the API key on your server, derive both identities from the same authenticated session, and include no secrets in token claims. JWTs are signed, not encrypted.

  • user.id and tenant.id must be stable strings of 1–255 characters. User IDs are local to a Tenant. Names are optional.
  • Grant user.admin only from verified application permissions. Store custom fields in each identity's metadata.
  • expiresInSeconds accepts 60–600 seconds and defaults to 300. The SDK keeps tokens in memory and renews them before expiry.

SDK options use camelCase. The signing helper sets AstralBeam's wire claims, issuer, and audience for you. Organization-management tokens serve internal tools and cannot authenticate chat or create a dashboard session.

Mint tokens without JavaScript

Use an HS256 JWT library in your backend language. The Quickstart's Rails example shows a token endpoint. To implement the signing yourself:

  1. Split the API key at its last _abo_. The part before it, key_<organizationId>_<id>, is the key ID. The rest, starting with abo_, is the secret.
  2. Hash the whole secret, including abo_, with SHA-256 and encode the digest as unpadded base64url. The bytes of that ASCII string are the HMAC key, because AstralBeam stores only this digest.
  3. Sign with the protected header { "alg": "HS256", "typ": "astralbeam+jwt", "kid": "<key ID>" } and these claims.
  • The user and tenant objects together must serialize to at most 8 KB of JSON, and the token to at most 16 KB.
  • AstralBeam allows 30 seconds of clock skew, so keep your server's clock synchronized.