Auth

The SDK supports two authentication modes for app builders: long-lived apiKey (the default) and short-lived scopeToken (per-request HS256 JWT, intended for browser and edge runtimes).

apiKey: server-side

Use this from any trusted server runtime: Node, Workers, container backends, agent runtimes. The key is a bel_live_… token tied to your account.

1import Beliefs from 'beliefs'
2
3const beliefs = new Beliefs({
4  apiKey: process.env.BELIEFS_KEY,
5  namespace: 'project-alpha',
6  writeScope: 'space',
7})

The key is sent as a Bearer header on every request. Get it from Profile > API Keys in the Studio dashboard. See Install for the full setup walkthrough.

scopeToken: browser, edge, untrusted runtimes

When you cannot put an apiKey on the device (browsers, edge functions, third-party plugins), mint a short-lived HS256 JWT on your server and hand it to the client. The SDK signs a fresh token from the configured claims on every request, so you never need to refresh tokens manually.

1import Beliefs from 'beliefs'
2
3const beliefs = new Beliefs({
4  scopeToken: {
5    secret: process.env.BELIEFS_SCOPE_TOKEN_SECRET!,
6    claims: {
7      scopeType: 'space',
8      scopeId: currentWorkspace.id,
9      actorUserId: currentUser.id,    // optional: who is acting
10      sessionId: currentSession.id,   // optional: for session pinning
11    },
12  },
13  namespace: 'project-alpha',
14})
15
16await beliefs.before('What did the user just say?')

Claims:

Two optional fields on the outer scopeToken config tune token lifetime:

• audience: restricts the minted token to a specific API endpoint. The engine rejects the token if the audience doesn't match. Use this to narrow tokens by deployment.
• ttlSeconds: overrides the default token lifetime (the engine sets a sensible default if omitted). Shorten this for high-sensitivity sessions; lengthen if you're seeing churn from repeated mints.

How it works:

1. Your server provisions a secret (32+ bytes of random) and stores it alongside any per-user/per-session claims.
2. The SDK accepts the secret and claims at construction time.
3. On each request, the SDK mints a fresh HS256 JWT from those claims and sends it as a Bearer token.
4. The engine verifies the signature against the shared secret and applies the claims as the request's scope.

The secret only stays safe when the SDK client is constructed on your server. If you instantiate the client in a browser, the secret is embedded in the bundle and effectively public. Provision a session-scoped secret you can revoke on logout, or proxy SDK calls through a server endpoint that holds the long-lived secret.

Mode switching is automatic. When you provide scopeToken, the SDK ignores any apiKey for that instance.

When to use which

Errors

BetaAccessError (HTTP 401/403): key missing, invalid, or revoked. The SDK surfaces a signupUrl for self-service requests:

1import Beliefs, { BetaAccessError } from 'beliefs'
2
3try {
4  await beliefs.before(input)
5} catch (err) {
6  if (err instanceof BetaAccessError) {
7    console.log(err.signupUrl)
8  }
9}

BeliefsError with code auth/missing_key: the SDK was constructed without any auth at all.