Users

An end-user is one person in your app. poolse knows them by two ids:

• id: poolse's UUID for the user. Token minting, mentions, call history and membership removal use it.
• external_id: your own id for the user, any string up to 255 characters, unique within your tenant. Conversation and member creation use it.

Everything on this page is called from your backend with an API key.

There is no API to list, fetch or delete users with an API key. A user can read their own record with GET /v1/me.

Provision or update a user

Creates the user if external_id is new in your tenant. Otherwise updates the existing user. Any valid API key works; no scope is needed.

On an existing user, only the fields you send change. A field you leave out keeps its stored value. So {"external_id": "u_42"} is a safe "make sure this user exists" call: it never clears a profile or unblocks a blocked user.

You do not have to call this before a user appears in a conversation. Unknown external_ids passed to POST /v1/conversations (member_external_ids) or POST /v1/conversations/:conversation_id/members (external_ids) are created automatically, with only external_id set. Call this endpoint when you want to set a profile, block someone, or get the poolse id to mint a token.

Request body

Response

200, for both a new and an existing user:

{
  "id": "8a7e2f9c-1234-4d5e-8f90-a1b2c3d4e5f6",
  "tenant_id": "65787825-3152-4c1e-9b8a-0d6f4e2a7c11",
  "external_id": "u_42",
  "display_name": "Ada",
  "avatar_url": null,
  "custom_data": {},
  "last_seen_at": null,
  "is_blocked": false,
  "inserted_at": "2026-06-02T08:14:00.123456Z",
  "updated_at": "2026-06-02T08:14:00.123456Z"
}

curl -X POST https://api.poolse.dev/v1/users \
  -H "Authorization: Bearer $POOLSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"u_42","display_name":"Ada"}'

Errors

Plus the API-key errors listed on Authentication.

Mint a user token

Mints a 1-hour JWT for one user. Your app sends it as Authorization: Bearer <token> to the end-user endpoints and the realtime socket. Each call returns a new token. Earlier tokens keep working until they expire.

Path parameters

No request body.

Response

200:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "bearer",
  "expires_in": 3600,
  "expires_at": "2026-06-02T09:14:00Z"
}

curl -X POST https://api.poolse.dev/v1/users/$POOLSE_USER_ID/tokens \
  -H "Authorization: Bearer $POOLSE_API_KEY"

Errors

A token minted for a blocked user is refused on use with 401 user_blocked, and with 401 unauthorized on the call grant endpoints (answer, decline, hang up, reconnect, ring).

Revoke a user token

Revokes one JWT before it expires. Every later request with it gets 401 token_revoked. The user's other tokens keep working.

Revoking also closes all of the user's open realtime sockets, because a socket does not record which token opened it. Clients that hold another valid token reconnect with it. To cut off a user completely, set is_blocked: true with POST /v1/users instead.

Request body

Response

200:

{
  "jti": "2tq8f0r9b6m1k3p5s7u9w1y3",
  "expires_at": "2026-06-02T09:14:00Z"
}

curl -X POST https://api.poolse.dev/admin/v1/tokens/revoke \
  -H "Authorization: Bearer $POOLSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"token\":\"$USER_JWT\"}"

Errors