Server integration

Your backend has two jobs: sign user tokens, and manage rooms, messages and users over REST. TypeScript has @kispi/chat/server, which wraps both; every other language does the same work directly. Pick your language in the tabs below.

Both jobs use a single sk_.

#User token spec

Claims:

aud, iss and nbf are not required. Which app you are is decided by the pk_ the browser sends on connect, not by the token. When verification fails the answer is a single 401 unauthorized whatever the reason — it won't tell you whether the signature was wrong or the token expired.

Go uses github.com/golang-jwt/jwt/v5 and Kotlin uses com.auth0:java-jwt. The rest needs nothing beyond the standard library.

import { createChatServer } from '@kispi/chat/server'

const chat = createChatServer({ secretKey: process.env.CHAT_SECRET_KEY! })
const token = chat.token({ userId: 'u_42', name: 'Hanna', ttlSeconds: 3600 })

import base64, hmac, hashlib, json, time

def b64u(b): return base64.urlsafe_b64encode(b).rstrip(b"=").decode()

def chat_token(sk, user_id, name, ttl=3600, avatar=None, meta=None):
    parts = sk.split("_")
    header = {"alg": "HS256", "typ": "JWT"}
    if len(parts) >= 3: header["kid"] = parts[1]
    iat = int(time.time())
    claims = {"sub": user_id, "name": name, "iat": iat, "exp": iat + ttl}
    if avatar: claims["avatar"] = avatar
    if meta: claims["meta"] = meta
    enc = lambda o: b64u(json.dumps(o, separators=(",", ":")).encode())
    signing_input = f"{enc(header)}.{enc(claims)}"
    sig = hmac.new(sk.encode(), signing_input.encode(), hashlib.sha256).digest()
    return f"{signing_input}.{b64u(sig)}"

func chatToken(sk, userID, name string, ttl time.Duration) (string, error) {
	now := time.Now()
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
		"sub":  userID,
		"name": name,
		"iat":  now.Unix(),
		"exp":  now.Add(ttl).Unix(),
	})
	if parts := strings.Split(sk, "_"); len(parts) >= 3 {
		token.Header["kid"] = parts[1]
	}
	return token.SignedString([]byte(sk))
}

fun chatToken(sk: String, userId: String, name: String, ttlSeconds: Long = 3600): String {
    val now = Instant.now()
    val builder = JWT.create()
        .withSubject(userId)
        .withClaim("name", name)
        .withIssuedAt(now)
        .withExpiresAt(now.plusSeconds(ttlSeconds))
    sk.split("_").let { if (it.size >= 3) builder.withKeyId(it[1]) }
    return builder.sign(Algorithm.HMAC256(sk))
}

#Server API

There is one way in: REST. The TypeScript SDK wraps it, so the three tabs below are three ways of calling the same endpoints.

const chat = createChatServer({ secretKey: process.env.CHAT_SECRET_KEY! })
const room = await chat.rooms.ensure({ key: 'lobby', type: 'public' })
await chat.messages.send(room.id, {
  sender: { id: 'system', name: 'Notice' },
  text: 'Maintenance in 10 minutes'
})

# Room get-or-create: 200 if it existed, 201 if it was created, same body either way
curl -X PUT https://api.chat.gravex.app/v1/rooms \
  -H "Authorization: Bearer $CHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "lobby", "type": "public"}'

# Send a system message. sender and clientMessageId are required
curl -X POST https://api.chat.gravex.app/v1/rooms/$ROOM_ID/messages \
  -H "Authorization: Bearer $CHAT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientMessageId": "c_1",
       "sender": {"id": "system", "name": "Notice"},
       "body": {"text": "Maintenance in 10 minutes"}}'

sender and clientMessageId are required when you send a message from the server. Query parameters are snake_case (purge_messages); JSON fields are camelCase.

users.* works only after that person has connected at least once; users come into being by connecting. Taking down everything someone sent (DELETE /v1/users/{userId}/messages) is not the same as deleting the account, and it removes up to a cap per call — call it again while purgeCapped is true.

The type you pick when creating a room:

A room's canonical identifier is its id. key is a human-assigned alias (lobby, order-1234) that the browser opens with chat.roomByKey(key). A channel created from the server has no owner, so if someone needs to post announcements with a user token, assign an owner or admin with the members API afterwards.

#Rotating keys

Rotate an sk_ in this order: issue new → deploy backend → verify → revoke old.

1. In the console's Keys screen, press New secret key. The full value appears only in that dialog.
2. Replace the sk_ on your backend and deploy. Both keys are live at this point.
3. Check that a token signed with the new key connects, and that your server API calls go through.
4. Revoke the old key in the console.

Do not revoke first. Turning off the old key stops the backend that signs with it, right then.

After you deploy, browsers still hold tokens signed with the old key. The engine checks the key that a token's kid points at, so those tokens keep working as long as the old key isn't revoked. Once one token lifetime has passed (one hour by default), everything in circulation has been re-signed with the new key — revoke then and nobody is dropped. Revoking sooner is safe too: an old token is replaced on the next call.

Rotating a pk_ has the same shape, plus one thing: allowed origins live on the key, not on the app. A pk_ with an empty list admits no browser page, so a new key has to carry the origins the current one has. If only the origins change, don't rotate the key — edit the list on the same key with Edit origins on the Keys screen.

Revocation takes effect immediately and cannot be undone. Losing a key doesn't lose data: users, rooms and messages belong to the app.

Separate production and development with apps, not keys. The app is the tenant, so the app is the data boundary. Create two apps and label them Production and Development in the console.