This feature is available on the following plans: Grow, Scale, Growth (legacy), Business (legacy)

How it works

1. You provision pending users via API. When someone joins your platform, your backend creates them in Heartbeat automatically.
2. Members log in with a magic link. They visit your community URL, enter their email, and they're in. No password, no sign-up.
3. Optionally, you own the profile. Disable in-app profile editing and sync changes from your system to Heartbeat via API.

Since there's no password involved, the gap between "SSO" and "API-provisioned passwordless login" is very small. Your members never create credentials on Heartbeat; they just verify their email.

Step 1: Get your API key

Go to Settings > API Keys in your Heartbeat admin dashboard and create a new API key.

All API requests use Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Step 2: Auto-provision pending users

When a member signs up on your platform, create them in Heartbeat with a /pendingUser PUT request:

curl -X PUT https://api.heartbeat.chat/v0/pendingUser \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "roleID": "YOUR_ROLE_ID"
  }'

Required fields: name, email, roleID

Optional fields: profilePicture (base64), groupIDs, bio

The pending user is created in your community immediately. As a pending user, their account is not activated until they first log in. This prevents unwanted platform notification emails from entering their inbox until they've onboarded into the community.

💡 Tip: If you prefer for the member to receive platform notification emails immediately after provisioning them, use the /users PUT request instead.

Step 3: Direct members to log in

Send your members to your community URL (e.g., https://yourcommunity.heartbeat.chat). They enter their email, receive a magic link, click it, and they're in.

Because you already provisioned them, there's no sign-up. From the member's perspective, this is functionally identical to SSO. New members will still need to complete onboarding, which is set up in your Onboarding settings. Check out how to Customize Onboarding Profiles →

Step 4 (Optional): Own the profile

To make the experience fully seamless, lock down profile editing in Heartbeat so your platform stays the single source of truth for user data.

1. Go to Settings > General
2. Toggle on Disable Profile Editing
3. Enter the URL where members should go to edit their profile (e.g., https://yourapp.com/profile/edit)

When this is enabled, members see a link to your profile edit page instead of editable fields in Heartbeat.

When they update their info on your platform, sync the changes to Heartbeat with a POST request:

curl -X POST https://api.heartbeat.chat/v0/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Smith-Doe",
    "bio": "Updated bio from external platform"
  }'

Updatable fields: name, bio, status, profilePicture (base64), linkedin, twitter, instagram

The member's email is used to look up who to update.

Step 5 (Optional): Handle offboarding

When a member leaves your platform, deactivate them in Heartbeat:

curl -X DELETE https://api.heartbeat.chat/v0/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com"
  }'

Need to bring someone back? Reactivate them:

curl -X POST https://api.heartbeat.chat/v0/users/reactivate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com"
  }'

Quick reference

With this setup, your system is the source of truth for identity. Heartbeat handles the login experience with magic links. Your users get a seamless, SSO-like flow (no SAML or OAuth infrastructure required).

Rate limits

The API allows 20 requests per second per API key.