How Authentication Works

Pulse uses two keys and a token to securely connect your users.

The Flow

┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│  Your User's │         │  Your        │         │  Pulse       │
│  Browser     │         │  Backend     │         │  Server      │
└──────┬──────┘         └──────┬───────┘         └──────┬───────┘
       │                       │                        │
       │  1. Page loads,       │                        │
       │     needs token       │                        │
       │ ─────────────────────>│                        │
       │                       │                        │
       │                       │  2. POST /auth/token   │
       │                       │     with sk_ key +     │
       │                       │     user info          │
       │                       │  ─────────────────────>│
       │                       │                        │
       │                       │  3. Returns JWT token  │
       │                       │  <─────────────────────│
       │                       │                        │
       │  4. Token sent to     │                        │
       │     browser           │                        │
       │ <─────────────────────│                        │
       │                       │                        │
       │  5. <pulse-widget>    │                        │
       │     connects with     │                        │
       │     pk_ + token       │                        │
       │  ──────────── WebSocket ─────────────────────> │
       │                       │                        │
       │  6. Real-time         │                        │
       │     collaboration!    │                        │
       │  <──────────── WebSocket ─────────────────────>│

Your Two Keys

When you create an environment in the Admin Panel, you get a key pair:

Publishable Key (pk_...)

• Goes in: Your frontend code (HTML, JavaScript)
• Purpose: Tells Pulse which environment this is
• Safe to expose: Yes — it can't do anything without a valid token

Secret Key (sk_...)

• Goes in: Your backend server only
• Purpose: Mints user tokens and authenticates REST API calls
• Safe to expose: No — treat this like a database password

Never put the secret key in frontend code

The sk_ key should only ever exist on your backend server. If it's exposed in client-side JavaScript, HTML, or a public git repository, anyone can create tokens and access your data. Rotate it immediately from the Admin Panel if compromised.

Minting Tokens

Your backend calls POST /auth/token to create a token for each user:

curl -X POST https://pulse.hire.rest/auth/token \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "name": "Alice Chen",
    "avatar": "https://example.com/avatars/alice.jpg"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Parameters

Field	Type	Required	Description
userId	string	Yes	Your user's unique ID from your system
name	string	Yes	Display name shown in the Pulse UI
avatar	string	No	URL to the user's profile picture

The token is a JWT that:

• Identifies this specific user
• Is scoped to your environment (can't access other environments)
• Is auto-assigned a color from the Pulse palette

When to Mint

Mint a token when:

• The user loads a page that has Pulse
• You can use your existing auth (sessions, cookies, etc.) to identify the user first

Tokens are short-lived. Pulse handles reconnection automatically — but your frontend should be able to fetch a fresh token if needed.

Putting It Together

<script src="https://pulse.hire.rest/sdk/pulse.js"></script>

<script>
async function initPulse() {
  // Your backend mints a token (using sk_ internally)
  const res = await fetch('/api/collab-token');
  const { token } = await res.json();

  const widget = document.createElement('pulse-widget');
  widget.setAttribute('api-key', 'pk_your_publishable_key');  // safe for frontend
  widget.setAttribute('token', token);                          // minted by your backend
  widget.setAttribute('room', 'dashboard');
  widget.setAttribute('endpoint', 'wss://pulse.hire.rest');
  document.body.appendChild(widget);
}
initPulse();
</script>

REST API Authentication

For server-to-server calls (creating threads, comments, etc. from your backend), use the secret key directly:

curl https://pulse.hire.rest/api/v1/rooms \
  -H "Authorization: Bearer sk_your_secret_key"

See the REST API docs for all available endpoints.