Authentication

All API requests require a key or token in the Authorization header:

Authorization: Bearer <key>

Key Types

Platform Keys

Created in the dashboard under Settings > Platform Keys. Full access to all platform API endpoints.

Never expose in client-side code.

Authorization: Bearer sk_pj_live_abc123

Session Tokens

Created via POST /v1/platform/sessions using a platform key. Scoped to a specific workspace and user. Expire after 1 hour by default (configurable).

Used for client-side SDK operations (wallet, API keys, provider keys).

Flow

1. Your backend creates a session with a platform key (workspace_id + user_id).
2. The API returns a sess_* token.
3. Your frontend uses the token for billing operations.

import { BillingClient } from '@assistant-billing/sdk';
 
const billing = new BillingClient({
  platformKey: process.env.ASSISTANT_BILLING_PLATFORM_KEY,
  workspaceId: 'ws_team_123',
  userId: 'user_456',
});
 
const { token } = await billing.sessions.create();
// Pass token to your frontend

// Frontend — pass the token to the billing client
import { BillingClient } from '@assistant-billing/sdk';
 
const client = new BillingClient({
  baseURL: 'https://api.assistant-billing.dev/v1/platform',
  getToken: () => fetchBillingToken(),
});

API Keys

Created per-workspace via the API or dashboard. Used for proxy requests (chat completions, embeddings).

Authorization: Bearer sk_ab_live_xyz789

• Stored as SHA-256 hash (never in plaintext).
• Support optional rate limits (RPM, TPM) and permissions (model/endpoint restrictions).
• Linked to a workspace via workspace_id.

Created via the SDK, the Dashboard, or the API Keys endpoint.

Temporary Keys

Short-lived API keys with automatic expiration. Use for CI/CD, trials, or guest access.

Authorization: Bearer sk_ab_tmp_live_def456

• Same capabilities as regular API keys (rate limits, budget caps, permissions).
• Always expire — default 24 hours, configurable via ttl or expires_at.
• Support budgets (monthly_budget_usd) and fine-grained permissions.
• Created via the SDK or the Temporary Keys endpoint.