Authentication

The SDK authenticates with a session token that your backend mints. Your organization API key stays on your server and never reaches a browser.

Your backend mints a session

Call POST /v1/token with your organization API key. The session it returns already carries the organization, the user, and the billing group.

Your page fetches it

Expose a small endpoint of your own that returns that response to the signed-in user.

The SDK takes it from there

Pass the response to initSidenet({ auth }). The SDK refreshes it on its own for as long as the session lives.

Minting the session

// The organization API key lives here and only here.
const tokens = await fetch('https://api.sidenet.ai/v1/token', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIDENET_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user: { id: 'user-789', name: 'Maya' },          // your stable id for the signed-in user
    billing_group: { id: 'acme-corp', name: 'Acme' }, // what this session's spend bills to
  }),
}).then((r) => r.json());

// → { access_token: 'snat_…', refresh_token: 'snrt_…',
//     token_type: 'Bearer', expires_in: 900, refresh_expires_in: … }
return tokens;

import { initSidenet } from 'sidenetai-sdk';

const tokens = await fetch('/my-backend/sidenet-token').then((r) => r.json());

await initSidenet({
  copilotId: 'copilot-456',
  auth: { ...tokens },
});

Because the session carries identity, the browser sends nothing but an Authorization header — no org id, no user id.

user and billing_group are both required, and both are objects with a required id and an optional name. A changed name renames the user or group in Studio; omitting it never blanks one you sent before. Full schema in the API reference.

The `auth` object

Field	Type	Description
`access_token`	`string`	The `snat_…` token. Lasts 15 minutes.
`refresh_token`	`string`	The `snrt_…` token. Its presence is what turns automatic refresh on.
`expires_in`	`number`	Lifetime in seconds, as returned by the API.
`onRefresh`	`(tokens) => void`	Optional. Fires with the rotated pair each time the SDK refreshes.
`onError`	`(error) => void`	Optional. Fires when refreshing fails — check `error.fatal`.

Automatic refresh

While refresh_token is present the SDK keeps the session alive by itself: it refreshes ahead of expiry, and retries once if a request still comes back 401. The open conversation is never interrupted.

Don’t run your own refresh loop alongside onRefresh. Refresh tokens are single-use, so two refreshers race and one will present a token the other already spent — which revokes the session.

Persisting across reloads

onRefresh hands you an object that is itself a valid auth, so restoring it is just a spread:

initSidenet({
  copilotId: 'copilot-456',
  auth: {
    ...JSON.parse(sessionStorage.getItem('sidenet-auth')),
    onRefresh: (t) => sessionStorage.setItem('sidenet-auth', JSON.stringify(t)),
    onError: (e) => { if (e.fatal) remintAndUpdate(); },
  },
});

Use sessionStorage, not localStorage. Refresh tokens are single-use, so two tabs sharing one pair means one eventually presents a token the other already spent — and the API revokes the session for both.

Keep the expiresAt that onRefresh includes. Re-deriving it from expires_in would treat a stale token as fresh, and the first request after a reload would 401.

When it fails

onError fires once with a reason. What you do depends on fatal:

`fatal`	Reasons	What it means
`true`	`session-revoked`, `refresh-rejected`, `refresh-missing`	The SDK has stopped using the credential and will not retry. Mint a new session and swap it in.
`false`	`refresh-failed`	Transient — a network blip or a 5xx. Already being retried; do nothing.

Swapping in a fresh session needs no teardown — it replaces the credential in place, as a unit, and the conversation on screen survives:

updateSidenetConfig({ auth: { ...newTokens, onRefresh, onError } });

This is also how you change who the user is: identity lives in the session, so mint a session for the new user and pass it here. Only copilotId is init-only.

Helpers

Function	Description
`refreshSidenetToken()`	Force a refresh now. Single-flight. Rarely needed.
`getSidenetAuthState()`	`{ hasToken, hasRefreshToken, expiresAt, refreshExpiresAt, dead }` — for diagnostics.

Upgrading from v2.0.123 or earlier

Session tokens replaced the old browser-side credential in v2.0.124. The identity fields are gone from initSidenet():

Before	Now
`orgId`, `userId`	Carried by the session — pass `user` to `POST /v1/token` instead.
`token` / `apiKey`	`auth: { access_token, refresh_token, expires_in }`
`groupName`, `groupId`	Still accepted, but prefer `billing_group` on `POST /v1/token`.
`runtimeAuth: [...]`	Removed from the browser — see Tool Credentials.
`updateSidenetConfig({ token })`	`updateSidenetConfig({ auth })`
`destroySidenet()` to change user	`updateSidenetConfig({ auth })` — no teardown needed.
`getAgents(copilotId, token, orgId, userId)`	`getAgents(copilotId)`

- initSidenet({
-   orgId: 'org-123',
-   userId: 'user-789',
-   copilotId: 'copilot-456',
-   token: 'sk_...',
- });
+ initSidenet({
+   copilotId: 'copilot-456',
+   auth: { ...tokens },   // from POST /v1/token, on your backend
+ });

Getting Started

Methods

Customization

Minting the session

The `auth` object

Automatic refresh

Persisting across reloads

When it fails

Helpers

​Minting the session

​The auth object

​Automatic refresh

​Persisting across reloads

​When it fails

​Helpers

Minting the session

The `auth` object

Automatic refresh

Persisting across reloads

When it fails

Helpers