Surge home page
SupportDashboard
Surge

Working with End Users

An End User is a person in your application who sends and receives messages through Surge's embeddable UI components. End Users are distinct from Dashboard Users (people who log in to hq.surge.app). If you're building a SaaS platform where your customers interact with Surge-powered messaging, your customers' customers are End Users.

What an End User is

End Users are provisioned via the Surge API and belong to a specific account. They're used in two ways:

  1. Embedded UI — the inbox and conversation components authenticate as a specific End User, showing that user's conversations and sending messages on their behalf
  2. Message attribution — messages sent or received on behalf of an End User include a user_id field, so you can trace activity back to the individual

End Users do not have Surge passwords or sessions. Authentication for embedded components goes through a short-lived JWT that your server generates.

Provision an End User

Create an End User via the API before you mount any components for them:

curl -X POST https://api.surge.app/accounts/YOUR_ACCOUNT_ID/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jordan",
    "last_name": "Patel",
    "metadata": {
      "internal_user_id": "u_9887"
    }
  }'
{
  "id": "usr_01jrzhe8d9enptypyx360pcmxu",
  "first_name": "Jordan",
  "last_name": "Patel",
  "metadata": {
    "internal_user_id": "u_9887"
  }
}

Store the returned id alongside the user's record in your database. You'll use it to generate component tokens and attribute messages.

Generate a component token

Your server generates a short-lived JWT for each user session. The JWT scopes the embedded component to that specific user's data.

The simplest path is the token endpoint:

curl -X POST https://api.surge.app/users/USER_ID/tokens \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "token": "eyJhbGciOiJFZERTQSIsImtpZCI6InNnbl8wMWouLi4ifQ..."
}

Return this token to your frontend and use it to mount the component. Generate a new token on each page load — tokens are short-lived.

Typical vertical SaaS flow

  1. When a customer signs up for your SaaS product, create a Surge End User via POST /accounts/:account_id/users. Store the id.
  2. When that customer loads a page in your app that includes embedded messaging, your server calls POST /users/:user_id/tokens to get a fresh JWT.
  3. Your frontend receives the JWT and mounts the Surge Inbox or Conversation component with it.
  4. The component shows only that user's conversations and sends messages attributed to them.
# On page load, server-side
@app.get("/api/surge-token")
async def get_surge_token(current_user: User):
    response = surge.users.create_token(id=current_user.surge_user_id)
    return {"token": response.token}
// In the browser
const { token } = await fetch("/api/surge-token").then(r => r.json());
SurgeEmbed.mount("inbox", {
  target: document.getElementById("surge-inbox"),
  token,
});

List and manage End Users

# List users in an account
curl "https://api.surge.app/accounts/YOUR_ACCOUNT_ID/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update a user
curl -X PATCH https://api.surge.app/users/USER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Jordan M." }'

# Delete a user
curl -X DELETE https://api.surge.app/users/USER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting an End User removes their Surge record but does not delete message history.

Next steps