Authentication

All SignalSmith API requests require authentication via the Authorization header and workspace scoping via the X-Workspace-ID header.

Required Headers

Every API request must include:

Authorization: Bearer <token>
X-Workspace-ID: <workspace-id>

Header	Required	Description
`Authorization`	Yes	Bearer token (Firebase ID token or API key)
`X-Workspace-ID`	Yes (for workspace-scoped endpoints)	UUID of the target workspace
`Content-Type`	Yes (for POST/PUT)	Must be `application/json`

Authentication Methods

1. Firebase ID Token (Browser/UI Clients)

Firebase ID tokens are used by the SignalSmith web UI and any client-side applications that authenticate through Firebase/GCP Identity Platform.

How it works:

The user signs in via Firebase Authentication (email/password, Google SSO, etc.)
The Firebase client SDK returns an ID token
The token is sent with each API request

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "X-Workspace-ID: 550e8400-e29b-41d4-a716-446655440000"

Token lifecycle:

Firebase ID tokens expire after 1 hour
The Firebase client SDK automatically refreshes tokens before expiry
On first use, SignalSmith performs JIT (Just-In-Time) provisioning to create an internal account for the authenticated user

Token verification:

The SignalSmith control plane verifies Firebase ID tokens using the Firebase Admin SDK. In development, you can configure the FIREBASE_AUTH_EMULATOR_HOST environment variable to use the Firebase Auth emulator.

2. API Keys (Server-to-Server)

API keys are long-lived credentials designed for server-to-server integrations, CI/CD pipelines, and automated workflows.

How it works:

Generate an API key via the API Keys endpoint or the SignalSmith UI
Store the key securely (it is only shown once at creation time)
Use the key as a Bearer token in the Authorization header

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/sources \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "X-Workspace-ID: 550e8400-e29b-41d4-a716-446655440000"

Key properties:

API keys are scoped to a specific workspace
Keys are stored as secure hashes; the raw key is only returned at creation time
Keys can be revoked at any time via the API or UI
Each key shows a key_prefix for identification (e.g., sk_live_abc1...)

Workspace Scoping

Most API endpoints operate within the context of a workspace. The X-Workspace-ID header determines which workspace’s data is accessed.

Exceptions that do not require X-Workspace-ID:

GET /api/v1/workspaces — lists workspaces the authenticated user belongs to
POST /api/v1/workspaces — creates a new workspace
Organization-level endpoints under /api/v1/organizations

Auth Flow Diagram

Client                    SignalSmith API             Firebase/GCP
  │                            │                          │
  │  Authorization: Bearer <token>                        │
  │  X-Workspace-ID: <id>     │                          │
  │ ─────────────────────────► │                          │
  │                            │  Verify token            │
  │                            │ ────────────────────────► │
  │                            │  Token valid + user info  │
  │                            │ ◄──────────────────────── │
  │                            │                          │
  │                            │  Check workspace membership
  │                            │  (internal DB lookup)
  │                            │                          │
  │  200 OK / 401 / 403       │                          │
  │ ◄───────────────────────── │                          │

Error Responses

401 Unauthorized

Returned when the token is missing, expired, or invalid:

{
  "error": "not authenticated"
}

403 Forbidden

Returned when the token is valid but the user lacks access to the requested workspace or resource:

{
  "error": "permission denied"
}

Best Practices

Never expose tokens in client-side code — Use API keys only in server-side environments.
Rotate API keys regularly — Revoke old keys and generate new ones periodically.
Use the minimum required scope — If you only need read access, use a role with read-only permissions.
Handle token expiry gracefully — For Firebase tokens, implement automatic refresh. For API keys, handle 401 responses by alerting the administrator.
Store API keys securely — Use environment variables or a secrets manager. Never commit keys to version control.

Overview API Keys