DOCS / GETTING STARTED

Authentication

Every request resolves to exactly one workspace — you can never read or mutate assets outside the workspace your credential is bound to. There are three ways to authenticate.

Session (first-party)

A Netlify Identity cookie (nf_jwt), used by the first-party dashboard. Sign-in is invite-only — your email has to be on the approved safelist. The first approved login auto-creates your profile and a personal workspace.

import { createCubsterClient } from '@cubster/assets'

// Same-origin dashboard: relative requests ride the session cookie.

const cubster = createCubsterClient({ baseUrl: '' })

API key (programmatic)

Send Authorization: Bearer csk_.... A key is bound to one workspace, which scopes every request it makes. Keys are shown in full exactly once, at creation; only a prefix is shown afterward. Never put a key in client-side code — keep it in an environment variable, server-side only.

const cubster = createCubsterClient({ apiKey: process.env.CUBSTER_API_KEY })

Upload grant (third-party browser upload)

A server holding a key mints a short-lived, single-use grant; a third-party browser then uploads one file directly with only that grant — no key, no cookies exposed to the browser.

// Server (has the key):

const grant = await cubster.uploads.createGrant({ maxSize: 5_000_000, ttlSeconds: 300 })

// Browser (no key):

const anon = createCubsterClient()

const asset = await anon.uploads.uploadWithGrant({ grant, file })

The invite gate

The approved-users safelist is the waitlist: an email with an "invited" status can sign in; anything else gets recorded (status "pending") so it can be invited later. A signed-in-but-not-approved session gets back { isApproved: false, email } from GET /api/v1/me rather than a hard error, so a client can show a "you're on the list" screen.