Skip to content
mondochat

Create a session from your server

POST
/v1/server/sessions
curl --request POST \
  --url https://app.mondochat.io/v1/server/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Mondochat-App-Id: <Mondochat-App-Id>' \
  --data '{ "avatar": "https://example.test/alice.jpg", "external_id": "alice", "name": "Alice" }'

Creates or updates the user with the profile you send and returns a session token for them, so a client without the embed can call the user routes. Server route: send the server secret as a bearer token with Mondochat-App-Id. tier must be a key of workspace.tiers; null clears it and leaving it out keeps the stored one.

Errors: 422 validation for an unknown role or tier or a reserved external id; 403 forbidden while a test app already has 50 users.

Guide: Sessions and tokens.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
ServerSessionRequest

The user to sign in from your server, with their profile.

object
avatar
Any of:
string
<= 2048 characters /^https://\S+$/
external_id
required
External Id

The user’s id on your site.

string
/^[A-Za-z0-9._:@-]{1,128}$/
lang
Any of:
string
Allowed values: it en es fr
name
required
Name

Display name.

string
>= 1 characters <= 100 characters
perms
Any of:
Perms

Per-user overrides carried in the perms claim; a null field changes nothing.

object
block
Any of:
boolean
buy
Any of:
boolean
call
Any of:
boolean
message
Any of:
boolean
messages_per_minute
Any of:
integer
>= 1
messages_to_unanswered
Any of:
integer
new_conversations_per_day
Any of:
integer
offers
Any of:
boolean
photo_consent_required
Any of:
boolean
photos
Any of:
boolean
photos_per_day
Any of:
integer
require_vouch
Any of:
boolean
see_presence
Any of:
boolean
start_conversation
Any of:
boolean
voice_per_day
Any of:
integer
role
Any of:
string
/^[A-Za-z0-9_-]{1,32}$/
tier
Any of:
string
/^[A-Za-z0-9_-]{1,32}$/

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
ServerSession

A session token minted from your server, with the user.

object
expires_at
required
Expires At

When the session token expires.

string format: date-time
session_token
required
Session Token

Bearer token for the user routes; valid 15 minutes.

string
user
required
User

The user the token is for.

object
avatar
Any of:
string
external_id
required
External Id

The user’s id on your site, the sub claim.

string
id
required
Id

The user’s id in mondochat.

string format: uuid
kind
required
Kind

member for a user your server signed in, guest for an anonymous one.

string
Allowed values: member guest
name
required
Name

Display name.

string
role
required
Role

A role key from the app’s roles.

string

Example 

{
  "expires_at": "2026-11-01T12:15:00Z",
  "session_token": "example-session-token",
  "user": {
    "avatar": "https://example.test/alice.jpg",
    "external_id": "alice",
    "id": "0199d6a0-1000-7000-8000-000000000001",
    "kind": "member",
    "name": "Alice",
    "role": "member"
  }
}

4XX

Section titled “4XX”

Problem

Media typeapplication/problem+json

An RFC 9457 problem: the body of every error answer.

object
code
required

The stable error code to branch on, such as policy_denied.

string
detail

What went wrong this time, when there is more to say.

string | null
errors

For validation, one entry per invalid field.

Array<object>

One invalid field.

object
loc

The path to the field.

array
msg

What is wrong with it.

string
instance

The path of the request.

string
reason

For policy_denied and limit_reached, the rule or limit that refused the request; for forbidden, a short cause such as you_blocked; for banned, temporary when the ban expires.

string
status
required

The HTTP status code.

integer
title
required

A short summary of the problem.

string
type
required

A URL that names the problem, https://app.mondochat.io/problems/<code>.

string

Example 

{
  "code": "policy_denied",
  "detail": null,
  "instance": "/v1/conversations/0199d6a0-2000-7000-8000-000000000001",
  "reason": "pins",
  "status": 403,
  "title": "Policy denied",
  "type": "https://app.mondochat.io/problems/policy_denied"
}