Set up your Domain

Your Domain is your tenant: its App Keys, claims, topics and data are isolated from every other Domain. When your account is set up you receive an owner key; this page takes you from there to a production-ready setup.

Sign in to the console#

Open the console's sign-in page and enter your Domain slug and the owner key. The key is exchanged for a token in your browser and is never stored; the session lasts as long as the key's token TTL (8 hours for the owner key).

The owner key is linked to a Domain Claim named "Owner" that grants W and R on the domain protocol: it can create App Keys and edit Domain Claims, nothing else yet.

Grant yourself the brokers#

Managing Event Broker and State Broker claims is a protocol of your Domain Claim, too:

1. Go to Domain → Claims and open Owner.
2. Add the protocols event and state, each with R and W.

After saving, the Event Broker and State Broker sections of the menu become available.

Plan your keys#

Use one App Key per component that talks to Thuum, each with the smallest set of permissions it needs. A typical web app has two:

Flags are explained in Claims and permissions: P publish or write, W purge (Event Broker) or manage, S subscribe, R read.

Create the claims#

A claim is a reusable bundle of permissions. In Event Broker → Claims, create:

• Browser chat: topic flags none, fallback data flags none, topic chat with P S R.
• Backend chat: topic flags R, fallback none, topic chat with P W R.

In State Broker → Claims, create Browser presence (presence: P S R) and Backend presence (presence: P R).

Claim topics are always Main Topics (no :): chat covers chat:lobby, chat:support:42 and every other sub-topic. See Topics.

Create the App Keys#

In Domain → App Keys, create web-browser (token TTL 60) and backend (token TTL 300). The form can link the new key to a claim of each kind right away. The plaintext key is shown once: store it in your secret manager, never in source control, never in a browser bundle.

A key links to at most one Domain Claim, one Event Broker claim and one State Broker claim; a claim links to any number of keys.

Configure retention#

Every Main Topic has a retention window, shared by all its sub-topics.

• Event Broker → Topics: by default a Main Topic keeps its newest 1000 events for at most one hour. For a chat you might set chat to max_events 50000 and ttl_seconds 604800 (7 days).
• State Broker → Topics: by default states never expire. For presence, set presence to ttl_seconds 120 so abandoned entries are cleaned up.

Configuring topics needs the claim's topic flags (R to read, W to change).

Do the same through the API#

Everything in the console is an API call, so the setup can live in a script. With the owner key (after granting event and state to the Owner claim):

import { ThuumClient, PUBLISH, WRITE, SUBSCRIBE, READ, combine } from '@thuum/client';

const thuum = new ThuumClient({ baseUrl: 'https://api.thuum.dev' });
const { token } = await thuum.exchangeToken('acme', process.env.THUUM_OWNER_KEY!);
const acme = thuum.domain('acme', token);

const browserChat = await acme.eventBroker.claims.create({
	name: 'Browser chat',
	topics: { chat: combine(PUBLISH, SUBSCRIBE, READ) }
});
const browserPresence = await acme.stateBroker.claims.create({
	name: 'Browser presence',
	topics: { presence: combine(PUBLISH, SUBSCRIBE, READ) }
});

const key = await acme.domain.keys.create({ name: 'web-browser', token_ttl_seconds: 60 });
await acme.eventBroker.claims.keys.link(browserChat.id, key.selector);
await acme.stateBroker.claims.keys.link(browserPresence.id, key.selector);
console.log('Store this key now:', key.key);

await acme.eventBroker.topics.put('chat', { max_events: 50_000, ttl_seconds: 604_800 });
await acme.stateBroker.topics.put('presence', { ttl_seconds: 120 });

The routes behind these calls are listed in Management API.

A key for the quickstart#

To follow the Quickstart, create an Event Broker claim and a State Broker claim named Quickstart, each with the topic demo set to P S R, and an App Key quickstart (token TTL 300) linked to both. Delete them when you are done: unlink the key, then delete the key and the claims.

Renew a key#

App Keys never change: to rotate one, open it in Domain → App Keys and choose Renew. The console creates a replacement with the same claim links and shows its plaintext. Old and new keys work side by side until you confirm; then the old one is unlinked and deleted. Deploy the new key before confirming, and nothing goes down.