PAMbaseDocs
Resources

Auth & tokens.

PAMbase has two kinds of credentials: connection tokens that apps use to call the API on a user's behalf, and session cookies that authenticate people in the hub and dev portal. This page is the focused reference on both, their lifetimes, and how to recover when one expires.

Token types & TTLs

CredentialTTLWho holds itPurpose
connection_token~365 daysYour app (server-side)Bearer credential for all app API calls
authorization code10 minutesTransient (callback)Single-use; exchanged once for a connection token
hub / dev session7 daysThe user (cookie)Logged-in session in the hub & dev portal UIs
2FA challenge5 minutesThe user (transient)Window to complete a two-factor step
No refresh tokens
PAMbase deliberately has no refresh tokens. A connection token is long-lived; when it expires or is revoked, you re-run the OAuth connect flow. There is nothing to silently refresh.

How apps authenticate

Every API call sends the connection token as a bearer credential. The SDK does this for you when you construct the client; with raw HTTP, set the header yourself.

typescript
import { PAMbaseApp } from "@pambase/sdk";


const pambase = new PAMbaseApp({
  baseUrl: process.env.PAMBASE_API_URL!,
  connectionToken: user.pambaseToken, // from your encrypted secret store
});
bash
curl http://localhost:4000/v1/identity/brief \
  -H "Authorization: Bearer <connection_token>"
Keep it server-side
The connection token grants access to the user's memory. Store it encrypted, server-side, and never ship it to the browser. Full guidance in Security.

How the hub & dev portal authenticate

Humans signing in to the hub (where users manage connections) and the dev portal (where you manage apps and webhooks) get a session cookie valid ~7 days. This is unrelated to your app's connection token — it authenticates a person in a browser, not an app calling the API. Sensitive actions may require a 2FA challenge, valid for 5 minutes.

The 401 → re-connect recovery

When a connection token is expired or revoked, the API returns 401 unauthorized (SDK: UnauthorizedError). The recovery is always the same: discard the token and re-run the connect flow.

typescript
import { UnauthorizedError } from "@pambase/sdk";


try {
  return await pambase.getContext({ intent: "app.daily" });
} catch (err) {
  if (err instanceof UnauthorizedError) {
    await secrets.delete(user.id);   // drop the dead token
    return redirect("/connect");     // re-run the OAuth connect flow
  }
  throw err;
}
Errors envelope
Auth failures return { error: { code: "unauthorized", message } } with HTTP 401. Scope problems are forbidden / scope_denied (403) — those mean re-consent, not re-connect-from-scratch. See Errors.

Related