Authentication

The REST API uses two layers of authentication:

API Key

Used for administrative operations (discovering layouts, creating tokens). Pass it as a header:

x-api-key: YOUR_API_KEY

The API key is a shared secret set via:

npx sst secrets set REST_API_KEY "your-secret-key"

To generate a secure key:

openssl rand -base64 32

Caution

Keep your API key server-side. Never embed it in client apps that ship to end users. Instead, proxy token requests through your own backend.

Bearer Token (JWT)

Used for sending audience actions. Obtained from the POST /token endpoint:

curl -X POST https://YOUR_API_URL/token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"layoutId": "YOUR_LAYOUT_ID"}'

Pass the returned token in subsequent action requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token properties

• Algorithm: HS256
• Signed with: AUDIENCE_CLIENT_SECRET (internal)
• Permissions: Audience-level (no admin access)
• Expiry: Tokens are lightweight and long-lived, but it’s good practice to refresh them periodically or on reconnect

Recommended flow

For production apps:

1. Your backend calls POST /token with the API key
2. Your backend returns the JWT to your client app
3. The client app uses the JWT directly for POST /action

This keeps the API key out of client code.