Users

A user is the identity an end customer sees. Cariosan doesn't authenticate users itself — your app already does that. Instead, you tell Cariosan about your users and it mints short-lived JWTs the client SDK can use to authenticate WebSocket connections and REST reads.

The external_id

Every user has two identifiers:

• An internal UUID, assigned by Cariosan, used as the foreign key target for memberships and messages.
• An external_id you supply ("user_alice", "auth0|123", etc.). This is the stable handle you use in every SDK call.

Upsert semantics

There is no "create" endpoint — just upsert. Call UpsertUser every time the user's name or avatar changes in your app:

client.UpsertUser(ctx, cariosan.UpsertUserRequest{
    ExternalID: "user_alice",
    Name:       "Alice Setiawan",
    AvatarURL:  "https://cdn.example.com/users/alice.jpg",
    Metadata:   map[string]any{"plan": "pro"},
})

• First call → row inserted, user.created webhook fires.
• Subsequent calls → row updated in place, no webhook.

Issuing a client JWT

Your backend mints a per-user JWT and returns it to the browser (or mobile client). The client SDK stores it in memory — never persist it to localStorage if you have alternatives, since anything in localStorage is exposed to XSS.

token, _ := client.IssueUserToken(ctx, "user_alice", 24*time.Hour)
// Return token.Token to the browser.

Deleting a user

DeleteUser hard-deletes the user row and cascades to their channel memberships.