Browse docs
On this page
API client
Manage Tenants and TenantUsers with @astralbeam/sdk/api. Use an API key on your server or a short-lived, scoped JWT in the browser.
TenantUsers do not need dashboard accounts. Token minting alone creates no records. SDK sessions synchronize signed identity before loading data. Direct API clients call getCurrentUser or provision records through the management API.
Server: organization API key
Keep the full organization API key on your server. The apiKey option sends it as X-API-Key.
import { createTenant, listTenants, updateTenant } from "@astralbeam/sdk/api"
const options = { apiKey: process.env.ASTRALBEAM_API_KEY! }
const tenant = await createTenant({ external_id: "acme", name: "Acme" }, options)
await updateTenant(tenant.id, { name: "Acme Inc." }, options)
const first = await listTenants({}, options)
if (first.page_after) {
const second = await listTenants({ page_after: first.page_after }, options)
// Pass second.page_before to page_before to return toward the first page.
}Use returned internal IDs in API resource paths and your application's external IDs in tokens. Fields follow the REST API's snake_case names. Timestamps are strings.
Current user
Call getCurrentUser after obtaining a JWT:
import { getCurrentUser } from "@astralbeam/sdk/api"
const currentUser = await getCurrentUser({ astralBeamToken: token })Ordinary tenant JWTs can synchronize their own Tenant and TenantUser. Organization JWTs return existing membership, including viewers, without provisioning. SDK components call this automatically after every token acquisition. See authentication.
Browser: tenant JWT
Obtain a short-lived token from your application's authenticated token endpoint, never expose an organization API key in browser code. The astralBeamToken option sends Authorization: Bearer.
import { listTenants, listUsersForTenant } from "@astralbeam/sdk/api"
const response = await fetch("/api/astralbeam/token", { method: "POST" })
const { token } = await response.json()
const options = { astralBeamToken: token }
const page = await listTenants({}, options)
const tenant = page.items[0]
if (tenant) {
const users = await listUsersForTenant(tenant.id, {}, options)
}Tenant JWT resource calls require signed user.admin: true and are restricted to that Tenant. Tenant JWT callers cannot create or update Tenants. Ordinary tenant users can use chat but cannot manage these resources. Stored TenantUser admin values do not change an already-issued token's authority.
Filtering, updates, and errors
- Filter lists with
{ "filter[external_id]": "acme" }. Matching is exact and case-sensitive. - Use
qfor literal, case-insensitive name/external-ID search. TenantUser lists also accept"filter[admin]": "true"or"false". Filters combine with AND. - Preserve all filters while paging. Clear both cursors when changing search, filters, organization, or Tenant.
- Pass either
page_afterorpage_before, not both. A null continuation means there is no page in that direction. Listings are live, not snapshots. - PATCH sends only the fields supplied.
name: nullclears a name. Metadata replaces the whole object, and{}clears it. - Set
apiUrlto your deployment's/apibase and usesignalto cancel a request. - API-key requests reject redirects. JWT requests follow Fetch defaults unless overridden. Requests do not retry automatically. Use trusted API URLs and redirect destinations. A failed or aborted mutation may already have committed. Low-level JWT calls do not refresh tokens automatically.
import { isAstralBeamApiError, updateTenant } from "@astralbeam/sdk/api"
try {
await updateTenant(tenantId, { metadata: {} }, { apiKey })
} catch (error) {
if (isAstralBeamApiError(error)) {
console.error(error.status, error.body?.detail, error.body?.issues)
// Available even when a gateway returns HTML instead of an API error:
const retryAfter = error.headers.get("Retry-After")
} else {
throw error
}
}Token expiry and recovery
API helpers accept a token string without managing a session or refreshing it. Tokens default to five minutes. Your endpoint must check the host session on every renewal.
- On an API
401, obtain a fresh token and retry a read once. If renewal fails or the retry returns401, stop and ask the user to sign in or check configuration. - On
403, do not loop on renewal. Check current organization membership/role, or the tenant JWT's signed admin claim. - On
429, respectRetry-After. Do not use new tokens to bypass the limit. - On
400, inspect query issues. A rejected cursor requires restarting the listing without it. On422, correct the submitted fields. - On create
409or an uncertain write outcome, look up the exact external ID and inspect the result before deciding to retry. Do not blindly replay mutations. - Cancel pending reads with
signalwhen switching identity or scope, and clear old rows and cursors. Responses fetched for the previous identity must not update the new view.
Chat and downloads
Use the headless chat SDK for streaming, tools, cancellation, and token refresh. For custom HTTP integrations, getChatConfig returns JSON, while runChat and getThreadAttachment return unread native Response objects.
runChat accepts ChatRunInput: a saved conversation UUID, one new user message, and forwardedProps.clientId. New runs stream SSE, while an accepted retry returns a JSON receipt. The headless SDK handles these details for you.
For files, getThreadAttachment returns proxied bytes by default. With delivery: "direct", it follows an authorized S3 storage URL without sending application credentials. Configure storage CORS for GET from the embedding origin and expose Content-Disposition if you read that header. The URL is a bearer credential valid for one minute, so do not persist or share it.
Chat requires a tenant JWT. Participant downloads require current conversation access. Administrative downloads also require tenantId and an authorized management credential. See the API reference for request and response schemas, including raw HTTP direct-download responses.
Browser: organization JWT
Use this for internal employee tools. The user must already be an organization member. Each request checks their current role: owners and developers can read and write, viewers can read. The issuing API key retains organization-wide authority.
In an authenticated server handler, mint a token for the verified member's email and authorized Organization UUID:
import { createAstralBeamOrganizationToken } from "@astralbeam/sdk/server"
const token = await createAstralBeamOrganizationToken({
apiKey: process.env.ASTRALBEAM_API_KEY!,
organizationId: organization.id,
email: session.user.email,
})Derive session and organization from your trusted backend state. The UUID must match the API key's organization. Return { token } with Cache-Control: no-store from a protected endpoint such as /api/astralbeam/organization-token. Keep session and CSRF checks, and restrict access to the intended employees.
In the browser:
import { listTenants } from "@astralbeam/sdk/api"
const response = await fetch("/api/astralbeam/organization-token", { method: "POST" })
const { token } = await response.json()
const tenants = await listTenants({}, { astralBeamToken: token })Tokens last five minutes by default, with expiresInSeconds from 60 to 600. Keep them in memory. Role changes apply on the next request. Minting alone does not verify membership. These tokens cannot authenticate chat or manage dashboard configuration. See API authentication for the full contract.