Quick Start

From zero to a working integration in under 5 minutes.

SAASIGNAL_KEY=sk_live_your_key_here

curl -X PUT https://api.saasignal.saastemly.com/infra/kv/hello \
  -H "Authorization: Bearer $SAASIGNAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "world"}'

curl https://api.saasignal.saastemly.com/infra/kv/hello \
  -H "Authorization: Bearer $SAASIGNAL_KEY"
# {"key": "hello", "value": "world", "expires_at": null}

curl -X POST https://api.saasignal.saastemly.com/infra/channels/my-channel/publish \
  -H "Authorization: Bearer $SAASIGNAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "ping", "data": {"hello": "world"}}'

npm install saasignal

SAASIGNAL_KEY=sk_live_your_key_here

import { createClient } from 'saasignal'

export const ss = createClient(process.env.SAASIGNAL_KEY!)

import { ss } from '@/lib/saasignal'
import { NextResponse } from 'next/server'

export async function POST(req: Request) {
  const session = await req.json()

  await ss.infra.kv.set(`session:${session.userId}`, session, { ttl: 86400 })

  return NextResponse.json({ ok: true })
}

Authentication

Core layer — Project tokens

All KV, Channels, and Jobs endpoints require a project token passed as a Bearer token:

curl https://api.saasignal.saastemly.com/infra/kv/mykey \
  -H "Authorization: Bearer sk_live_abc123..."

import { createClient } from 'saasignal'

// Reads SAASIGNAL_TOKEN or SAASIGNAL_API_KEY from env automatically if no arg passed
const ss = createClient('sk_live_abc123...')

// Or set SAASIGNAL_API_KEY in your environment:
const ss2 = createClient()

Tokens are scoped per-project and per-capability. The wildcard scope * grants access to all routes. Resource wildcards (e.g. kv:*) grant all actions on that resource. Available scopes:

Infrastructure

Logistics

Delivery

Platform

Browser tokens

API keys (sk_live_) must never be exposed in client-side code. For browser-safe access, exchange an API key for a short-lived browser token (bt_*) via a server-side call:

curl -X POST https://api.saasignal.saastemly.com/core/tokens/browser \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["channels:subscribe", "kv:read"], "ttl": 900 }'

// Server-side: create a browser token for the client
const { token, expires_at } = await SaaSignalClient.createBrowserToken({
  apiKey: 'sk_live_abc123...',
  scopes: ['channels:subscribe', 'kv:read'],
  ttl: 900,
})

// Send `token` (bt_...) to the browser — it's safe to expose

Browser tokens are short-lived JWTs (default 15 minutes, max 30 minutes). They carry only the scopes you specify, which must be a subset of the parent API key's scopes. Use them in client-side JavaScript wherever you would otherwise need an API key — for example, subscribing to channels or reading KV data from the browser.

Platform layer — User JWT

Dashboard-type operations (managing orgs, projects, billing) use a session token obtained by signing in:

POST /api/auth/sign-in/email
Content-Type: application/json

{ "email": "you@acme.com", "password": "..." }

The response includes a token field. Use it as Authorization: Bearer <token> for Platform routes. Better Auth also sets a session cookie automatically for browser clients.

Token Model

1 token ≈ $1 of metered SaaSignal platform spend. Billing tracks underlying compute, storage, media, realtime, and logistics provider cost as closely as the platform can observe it. Every metered API response includes an X-Microtokens-Used header showing the token cost of that request.

Check remaining balance:

curl "https://api.saasignal.saastemly.com/core/tokens/balance?org_id=org_123" \
  -H "Authorization: Bearer <session_token>"

const balance = await ss.core.billing.tokenBalance('org_123')
console.log(balance.total) // 4.82

{
  "org_id": "org_123",
  "included_remaining": 3.42,
  "topup_balance": 1.40,
  "total": 4.82
}