Dbrij API Documentation

Full reference for the Dbrij public API: authentication, meetings, chat, messages and webhooks.

Introduction

The Dbrij Developer API lets you embed real time Meetings (audio/video on LiveKit) and Chat into your own product. You operate on behalf of your own end users, Dbrij provisions a managed identity for each, so meetings, chat authorship and participant lists all map back to your user ids.

Base URLhttps://api.dbrij.com/api
FormatJSON in, JSON out
AuthAuthorization: Bearer <key>

Every endpoint is relative to that base. All requests and responses are JSON. Authenticate with an API key (see Authentication).

Create a meeting

Request
POST /meetings
{
  "title": "Sales demo",
  "mode": "video",
  "host": { "externalUserId": "user_42", "displayName": "Jane" },
  "participants": [{ "externalUserId": "user_99", "displayName": "Sam" }]
}
Response
{
  "success": true,
  "data": {
    "id": "b1f2…",
    "status": "live",
    "mode": "video",
    "title": "Sales demo",
    "code": "abc-defg-hij",
    "scheduledFor": null,
    "startedAt": "2026-06-29T12:00:00.000Z",
    "endedAt": null,
    "isRecorded": false,
    "recordingUrl": null,
    "createdAt": "2026-06-29T12:00:00.000Z"
  }
}

Endpoints

Use the sections menu to browse each area, every endpoint lists its parameters, an example request, and an example response.

Quickstart & SDK

Dbrij ships SDKs and packages for every stack below. Each one, with what it does, how to install it and a quick start, is on the apps page.

  • TypeScript 11 packages
  • JavaScript 8 packages
  • Node.js 7 packages
  • Browsers 11 packages
  • React Native 5 packages
  • Capacitor 3 packages
  • Python 1 package
  • Go 3 packages
  • Swift 2 packages
  • iOS 6 packages
  • Kotlin 2 packages
  • Android 6 packages
  • Dart 4 packages
  • Flutter 4 packages
  • Docker 1 package
  • Kubernetes 1 package
  • Command line 1 package

The official client is a single, zero dependency file (Node 18+ and browsers). Download dbrij-sdk.js and drop it into your project.

1 · Initialise
import { DbrijClient } from './dbrij-sdk.js';

const dbrij = new DbrijClient({
  apiKey: process.env.DBRIJ_API_KEY,   // a key from your Developer API dashboard
  baseUrl: 'https://api.dbrij.com/api',
});
2 · Start a meeting + get a join token
const meeting = await dbrij.createMeeting({
  title: 'Onboarding call',
  mode: 'video',
  host: { externalUserId: 'user_42', displayName: 'Jane' },
});

const { url, token } = await dbrij.mintToken(meeting.id, {
  externalUserId: 'user_99', displayName: 'Sam',
});  // → hand url + token to the LiveKit client SDK
3 · Open a chat and send a message
const convo = await dbrij.createConversation({
  type: 'direct',
  members: [{ externalUserId: 'user_42' }, { externalUserId: 'user_99' }],
});

await dbrij.sendMessage(convo.id, {
  author: { externalUserId: 'user_42' },
  body: 'Welcome aboard! 👋',
});

Errors throw a DbrijError with .status + .body. The file also exports verifyWebhook(rawBody, header, secret).

Glass in a native app

Tracking a website with Glass is one script tag. For a React Native app, use the @dbrij/glass-native package instead: sessions, screen views, taps and custom events land in the same Glass dashboard, with device shown as iOS or Android. Session replay stays web only; native sessions appear without a recording.

React Native
import AsyncStorage from '@react-native-async-storage/async-storage';
import { AppState, Platform } from 'react-native';
import { createGlass } from '@dbrij/glass-native';

export const glass = createGlass({
  siteKey: 'gk_your_site_key',          // Glass -> Sites
  platform: { os: Platform.OS === 'ios' ? 'ios' : 'android', appVersion: '1.4.2' },
  storage: AsyncStorage,
});

AppState.addEventListener('change', (s) => {
  if (s === 'active') glass.onForeground();
  else if (s === 'background') glass.onBackground();
});

// then, anywhere:
glass.screen('Checkout');
glass.track('signup', { plan: 'pro' });
glass.identify('user_1234');

The SDK batches events, persists an offline queue, honors the site's quota kill switch, and never throws into your app. Nothing is collected beyond what you call.

Glass in Swift, Kotlin or Flutter

Pure native apps get the same tracking through a single drop-in file per platform, zero dependencies each: glass-tracker.swift, GlassTracker.kt or glass_tracker.dart. Same API everywhere: screen, track, identify, tap. All of them batch, keep a bounded offline queue, honor the quota kill switch, and never throw into your app.

Swift (iOS)
let glass = GlassTracker(siteKey: "gk_your_site_key", appVersion: "1.4.2")
// lifecycle is observed automatically on iOS
glass.screen("Checkout")
glass.track("signup", props: ["plan": "pro"])
glass.identify("user_1234")
glass.tap(xPct: 48, yPct: 88, label: "buy-button")
Kotlin (Android)
val glass = GlassTracker(application, GlassTracker.Config(
  siteKey = "gk_your_site_key", appVersion = "1.4.2",
))
// lifecycle is observed automatically via ActivityLifecycleCallbacks
glass.screen("Checkout")
glass.track("signup", mapOf("plan" to "pro"))
glass.identify("user_1234")
glass.tap(48.0, 88.0, "buy-button")
Flutter (Dart)
final glass = GlassTracker(GlassConfig(
  siteKey: 'gk_your_site_key',
  platformOs: Platform.isIOS ? 'ios' : 'android',
  appVersion: '1.4.2',
));
// wire a WidgetsBindingObserver: resumed -> glass.onForeground(),
// paused -> glass.onBackground(); a NavigatorObserver calls glass.screen(name)
glass.track('signup', {'plan': 'pro'});

Sessions from native apps show up in the Glass dashboard with device iOS or Android. Session replay is web only; native sessions appear without a recording.

Authentication

Authenticate every request with an API key from your Developer API dashboard (sign in with your normal Dbrij account), sent as a Bearer token.

Authorization header
Authorization: Bearer dbrij_live_xxxxxxxxxxxxxxxxxxxxxxxx

Test keys (dbrij_test_…) are never billed. Chat messages and meetings are real so you can watch them work, and capped so a test key cannot run production: 500 chat messages and 25 meetings a day, and a test meeting holds 2 people for 10 minutes.

Use test keys while building and live keys in production. Keys carry scopes; a request missing a required scope returns 403. Keys for email, SMS, search and support are made in Send, Ping, Search and Resolve, each with its own docs.

Every success response is wrapped in an envelope: { "success": true, "data": … }. Read your payload from data, never from the top level, the Response examples throughout these docs show the envelope. Errors are wrapped the same way with success: false (see Errors and usage).

meetings:readscopeList/read meetings, participants, summaries.
meetings:writescopeCreate/end/cancel meetings, mute/remove participants.
meetings:tokensscopeMint LiveKit join tokens.
chat:readscopeList/read conversations and messages.
chat:writescopeCreate conversations, send messages, manage members, react.

Managed users

You never create Dbrij user accounts. Instead, every call carries an externalUserId, your own identifier for one of your end users. Dbrij transparently provisions and reuses a managed identity behind it.

Most endpoints take an actor reference wherever a person is needed (a host, message author, member or reactor):

externalUserId*stringYour stable id for the end user.
displayNamestringThe user's name (kept fresh on each call).
avatarUrlstringURL to the user's avatar.
Actor reference
{ "externalUserId": "user_42", "displayName": "Jane Doe", "avatarUrl": "https://…/jane.png" }

Meetings

Standalone audio/video meetings, created with an arbitrary host + participants, instant or scheduled, not tied to a conversation. (For a call inside a chat, see Calls.) Tokens are minted per end user for the LiveKit client SDK.

An actor reference: { "externalUserId": string, "displayName"?: string, "avatarUrl"?: string }.

POST/meetingsmeetings:write

Create a meeting

Create an instant meeting (starts live) or schedule one for later. The host and any participants are your own end users.

PATH / BODY PARAMETERS

titlestringDisplay title. Defaults to a generated name.
mode'video' | 'voice'Camera call or audio only. Default 'video'.
scheduledForstring (ISO-8601)If set in the future, the meeting is scheduled rather than started now.
durationMinutesnumberPlanned length cap (5 to 1440).
hostActorRefThe hosting end user. Defaults to your app actor.
participantsActorRef[]End users invited up front (optional, you can mint tokens for anyone later).
Request
curl -X POST https://api.dbrij.com/api/meetings \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Sales demo",
  "mode": "video",
  "host": { "externalUserId": "user_42", "displayName": "Jane" },
  "participants": [{ "externalUserId": "user_99", "displayName": "Sam" }]
}'
Request body
{
  "title": "Sales demo",
  "mode": "video",
  "host": { "externalUserId": "user_42", "displayName": "Jane" },
  "participants": [{ "externalUserId": "user_99", "displayName": "Sam" }]
}
Response 200
{
  "success": true,
  "data": {
    "id": "b1f2…",
    "status": "live",
    "mode": "video",
    "title": "Sales demo",
    "code": "abc-defg-hij",
    "scheduledFor": null,
    "startedAt": "2026-06-29T12:00:00.000Z",
    "endedAt": null,
    "isRecorded": false,
    "recordingUrl": null,
    "createdAt": "2026-06-29T12:00:00.000Z"
  }
}
GET/meetingsmeetings:read

List meetings

Returns the 50 most recent meetings created by your app, newest first.

Request
curl -X GET https://api.dbrij.com/api/meetings \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": [ { "id": "b1f2…", "status": "ended", "mode": "video", "title": "Sales demo", … } ]
}
GET/meetings/:idmeetings:read

Get a meeting

Fetch a single meeting, including its live participant count.

PATH / BODY PARAMETERS

id*string (path)The meeting id.
Request
curl -X GET https://api.dbrij.com/api/meetings/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": { "id": "b1f2…", "status": "live", "participantCount": 2, … }
}
POST/meetings/:id/endmeetings:write

End a meeting

End a live meeting. Everyone is disconnected and the room is closed.

PATH / BODY PARAMETERS

id*string (path)The meeting id.
Request
curl -X POST https://api.dbrij.com/api/meetings/:id/end \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": { "id": "b1f2…", "status": "ended", "endedAt": "2026-06-29T12:30:00.000Z", … }
}
POST/meetings/:id/cancelmeetings:write

Cancel a meeting

Cancel a scheduled meeting before it starts.

PATH / BODY PARAMETERS

id*string (path)The meeting id.
Request
curl -X POST https://api.dbrij.com/api/meetings/:id/cancel \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": { "id": "b1f2…", "status": "cancelled", … }
}
POST/meetings/:id/tokensmeetings:tokens

Mint a join token

The embed primitive. Returns a LiveKit URL + token for one of your end users. Hand both to the LiveKit client SDK in your app to join the call.

PATH / BODY PARAMETERS

id*string (path)The meeting id.
Request
curl -X POST https://api.dbrij.com/api/meetings/:id/tokens \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "user_99", "displayName": "Sam", "canPublish": true }'
Request body
{ "externalUserId": "user_99", "displayName": "Sam", "canPublish": true }
Response 200
{
  "success": true,
  "data": {
    "url": "wss://your-project.livekit.cloud",
    "token": "eyJhbGciOi…",
    "identity": "user_99",
    "meeting": { "id": "b1f2…", "status": "live", "mode": "video" }
  }
}
GET/meetings/:id/participantsmeetings:read

List participants

The end users currently connected to the call.

PATH / BODY PARAMETERS

id*string (path)The meeting id.
Request
curl -X GET https://api.dbrij.com/api/meetings/:id/participants \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": [ { "externalUserId": "user_99", "name": "Sam" } ]
}
POST/meetings/:id/participants/mutemeetings:write

Mute a participant

Mute an end user's microphone on the server (host control). Returns 204 No Content.

PATH / BODY PARAMETERS

id*string (path)The meeting id.
Request
curl -X POST https://api.dbrij.com/api/meetings/:id/participants/mute \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "user_99" }'
Request body
{ "externalUserId": "user_99" }

Returns 204 (no body).

DELETE/meetings/:id/participants/:externalUserIdmeetings:write

Remove a participant

Kick an end user from the call and block their rejoin. Returns 204 No Content.

PATH / BODY PARAMETERS

id*string (path)The meeting id.
externalUserId*string (path)The end user to remove.
Request
curl -X DELETE https://api.dbrij.com/api/meetings/:id/participants/:externalUserId \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

Returns 204 (no body).

GET/meetings/:id/summarymeetings:read

Meeting summary

Attendance and metrics after the call (who joined, durations).

PATH / BODY PARAMETERS

id*string (path)The meeting id.
Request
curl -X GET https://api.dbrij.com/api/meetings/:id/summary \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": { "meetingId": "b1f2…", "attendees": [ … ], "durationMs": 1800000 }
}
POST/meetings/:id/recordingmeetings:write

Start / stop recording

Toggle recording on a live meeting. When you stop (or the call ends), a recording.ready webhook fires with the URL once processing completes. Requires the server to have recording configured.

PATH / BODY PARAMETERS

id*string (path)The meeting id.
on*booleantrue to start, false to stop.
Request
curl -X POST https://api.dbrij.com/api/meetings/:id/recording \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "on": true }'
Request body
{ "on": true }
Response 200
{
  "success": true,
  "data": { "id": "b1f2…", "status": "live", "isRecorded": true, … }
}

Calls

A call is a real time audio/video session that lives inside a conversation: ring a 1:1 chat, or start a group call. Unlike a standalone meeting, a call is bound to the chat: its audience is the conversation's members, and a "call started" card appears in the thread.

Typical flow: open a conversation → start a call in it → mint a join token for each member.

POST/conversations/:id/callsmeetings:write

Start a call in a conversation

Rings the conversation members and returns a Meeting object. The initiator must be a member of the conversation.

PATH / BODY PARAMETERS

id*string (path)The conversation id.
initiator*ActorRefThe end user starting the call (a member of the conversation).
mode'video' | 'voice'Camera call or audio only. Default 'video'.
titlestringOptional title (defaults to the chat name).
Request
curl -X POST https://api.dbrij.com/api/conversations/:id/calls \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "initiator": { "externalUserId": "user_42" },
  "mode": "video"
}'
Request body
{
  "initiator": { "externalUserId": "user_42" },
  "mode": "video"
}
Response 200
{
  "success": true,
  "data": { "id": "b1f2…", "status": "live", "mode": "video", "title": "Project room", … }
}

Then join + control it like any meeting

The response is a Meeting object. Use its id with the Meetings endpoints to join and manage the call: POST /meetings/:id/tokens (join), /participants, /participants/mute, /recording, /end.

SDK: call a chat, then join
// 1) An existing conversation (or create one)
const convo = await dbrij.createConversation({
  type: 'direct',
  members: [{ externalUserId: 'user_42' }, { externalUserId: 'user_99' }],
});

// 2) Start the call (rings the members)
const call = await dbrij.startCall(convo.id, {
  initiator: { externalUserId: 'user_42' },
  mode: 'video',
});

// 3) Mint a join token for each member → hand to the LiveKit SDK
const { url, token } = await dbrij.mintToken(call.id, { externalUserId: 'user_99' });

Chat

Conversations and messages among your end users.

An actor reference: { "externalUserId": string, "displayName"?: string, "avatarUrl"?: string }.

POST/conversationschat:write

Create a conversation

Open a direct (1:1) or group conversation among your end users. For a direct chat pass exactly two members; for a group pass a title.

PATH / BODY PARAMETERS

type*'direct' | 'group'Conversation kind.
titlestringRequired for a group.
members*ActorRef[]The end users in the conversation (exactly 2 for direct).
Request
curl -X POST https://api.dbrij.com/api/conversations \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "direct",
  "members": [
    { "externalUserId": "user_42" },
    { "externalUserId": "user_99" }
  ]
}'
Request body
{
  "type": "direct",
  "members": [
    { "externalUserId": "user_42" },
    { "externalUserId": "user_99" }
  ]
}
Response 200
{
  "success": true,
  "data": { "id": "c7a1…", "type": "direct", "title": "Sam" }
}
GET/conversationschat:read

List conversations

Your app's 50 most recent conversations.

Request
curl -X GET https://api.dbrij.com/api/conversations \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": [ { "id": "c7a1…", "type": "group", "title": "Project room" } ]
}
GET/conversations/:idchat:read

Get a conversation

Fetch a conversation with its member list (mapped back to your external user ids).

PATH / BODY PARAMETERS

id*string (path)The conversation id.
Request
curl -X GET https://api.dbrij.com/api/conversations/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": {
    "id": "c7a1…",
    "type": "group",
    "title": "Project room",
    "memberCount": 3,
    "members": [ { "externalUserId": "user_42", "name": "Jane", "avatarUrl": null } ]
  }
}
POST/conversations/:id/memberschat:write

Add members

Add end users to a group conversation.

PATH / BODY PARAMETERS

id*string (path)The conversation id.
Request
curl -X POST https://api.dbrij.com/api/conversations/:id/members \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "members": [ { "externalUserId": "user_77", "displayName": "Alex" } ] }'
Request body
{ "members": [ { "externalUserId": "user_77", "displayName": "Alex" } ] }
Response 200
{
  "success": true,
  "data": { "id": "c7a1…", "type": "group", "memberCount": 4, "members": [ … ] }
}
DELETE/conversations/:id/members/:externalUserIdchat:write

Remove a member

Remove an end user from a group. Returns 204 No Content.

PATH / BODY PARAMETERS

id*string (path)The conversation id.
externalUserId*string (path)The end user to remove.
Request
curl -X DELETE https://api.dbrij.com/api/conversations/:id/members/:externalUserId \
  -H "Authorization: Bearer $DBRIJ_API_KEY"

Returns 204 (no body).

POST/conversations/:id/messageschat:write

Send a message

Post a message authored by one of your end users, optionally with media attachments. Fires a message.created webhook so you can deliver it to other clients.

PATH / BODY PARAMETERS

id*string (path)The conversation id.
author*ActorRefThe end user sending the message.
body*stringMessage text (may be empty when sending media).
attachmentsAttachment[]Up to 10 media items (see the Media tab). Each: { name, kind, url, sizeLabel?, durationMs?, mimeType?, width?, height?, thumbnailUrl? }.
parentMessageIdstringPost as a threaded reply.
quotedMessageIdstringQuote another message.
Request
curl -X POST https://api.dbrij.com/api/conversations/:id/messages \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "author": { "externalUserId": "user_42" },
  "body": "Here's the deck 👇",
  "attachments": [
    { "name": "deck.pdf", "kind": "file", "url": "https://…/deck.pdf", "sizeLabel": "2.1 MB" }
  ]
}'
Request body
{
  "author": { "externalUserId": "user_42" },
  "body": "Here's the deck 👇",
  "attachments": [
    { "name": "deck.pdf", "kind": "file", "url": "https://…/deck.pdf", "sizeLabel": "2.1 MB" }
  ]
}
Response 200
{
  "success": true,
  "data": {
    "id": "m9c2…",
    "conversationId": "c7a1…",
    "authorExternalUserId": "user_42",
    "body": "Hey, are we still on for 3pm?",
    "createdAt": "2026-06-29T12:05:00.000Z",
    "parentMessageId": null,
    "reactions": []
  }
}
GET/conversations/:id/messageschat:read

List messages

Paginated message history, oldest last. Use the timestamp of the earliest message as the next `before` cursor.

PATH / BODY PARAMETERS

id*string (path)The conversation id.

QUERY PARAMETERS

limitnumberMax messages (1 to 100, default 30).
beforestring (ISO-8601)Return messages created before this time.
Request
curl -X GET https://api.dbrij.com/api/conversations/:id/messages \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": [ { "id": "m9c2…", "authorExternalUserId": "user_42", "body": "…", "createdAt": "…" } ]
}
POST/messages/:id/reactionschat:write

Toggle a reaction

Add or remove an emoji reaction on a message, as one of your end users.

PATH / BODY PARAMETERS

id*string (path)The message id.
Request
curl -X POST https://api.dbrij.com/api/messages/:id/reactions \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user": { "externalUserId": "user_99" }, "emoji": "👍" }'
Request body
{ "user": { "externalUserId": "user_99" }, "emoji": "👍" }
Response 200
{
  "success": true,
  "data": [ { "emoji": "👍", "count": 1, "mine": true } ]
}
PATCH/messages/:idchat:write

Edit a message

Edit a message's text. Only the original author may edit.

PATH / BODY PARAMETERS

id*string (path)The message id.
Request
curl -X PATCH https://api.dbrij.com/api/messages/:id \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user": { "externalUserId": "user_42" }, "body": "Edited text" }'
Request body
{ "user": { "externalUserId": "user_42" }, "body": "Edited text" }
Response 200
{
  "success": true,
  "data": { "id": "m9c2…", "body": "Edited text", … }
}
POST/messages/:id/deletechat:write

Delete a message

Redact (soft delete) a message. Returns 204 No Content.

PATH / BODY PARAMETERS

id*string (path)The message id.
Request
curl -X POST https://api.dbrij.com/api/messages/:id/delete \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user": { "externalUserId": "user_42" } }'
Request body
{ "user": { "externalUserId": "user_42" } }

Returns 204 (no body).

POST/conversations/:id/readchat:write

Mark read

Mark a conversation read up to now, as one of your end users (emits a read receipt). Returns 204.

PATH / BODY PARAMETERS

id*string (path)The conversation id.
Request
curl -X POST https://api.dbrij.com/api/conversations/:id/read \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user": { "externalUserId": "user_99" } }'
Request body
{ "user": { "externalUserId": "user_99" } }

Returns 204 (no body).

GET/conversations/:id/receiptschat:read

Read receipts

Where each member has read to.

PATH / BODY PARAMETERS

id*string (path)The conversation id.
Request
curl -X GET https://api.dbrij.com/api/conversations/:id/receipts \
  -H "Authorization: Bearer $DBRIJ_API_KEY"
Response 200
{
  "success": true,
  "data": [ { "externalUserId": "user_42", "name": "Jane", "avatarUrl": null, "lastReadAt": "2026-06-29T12:06:00.000Z" } ]
}

Sign in with Dbrij

Quick start

  1. Get a client id. In Dbrij Auth, under Sign in with Dbrij, add your product, say whether it is a website with its own server or a phone, desktop or browser only app, and add its redirect address. A website gets a secret: copy it, it shows once. An app gets no secret and uses PKCE instead.
  2. Put the button on your sign in page. Any link or button that opens your start route works.
  3. Add the two routes below to your server. Set DBRIJ_CLIENT_ID and DBRIJ_CLIENT_SECRET in its environment.
  4. Try it. Press the button, approve on Dbrij, and you land back signed in.

Sign in with Dbrij is free: no charge per sign in, and sign in products never use up your Developer plan. An account can have up to 20 of them.

The button
<a href="/auth/dbrij/start" class="dbrij-signin">
  Sign in with Dbrij
</a>
server.js (Node and Express, a website with its own server): the whole integration
// npm install express express-session
import crypto from 'node:crypto';
import express from 'express';
import session from 'express-session';

const DBRIJ = 'https://api.dbrij.com/api';
const CLIENT_ID = process.env.DBRIJ_CLIENT_ID;
const CLIENT_SECRET = process.env.DBRIJ_CLIENT_SECRET; // server only, never in the browser
const REDIRECT_URI = 'https://yourapp.com/auth/dbrij/callback'; // registered exactly

const app = express();
app.use(session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false }));

// 1. Your button lands here: remember a state and a PKCE verifier, then go to Dbrij.
app.get('/auth/dbrij/start', (req, res) => {
  const state = crypto.randomBytes(16).toString('base64url');
  const verifier = crypto.randomBytes(32).toString('base64url');
  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
  req.session.dbrij = { state, verifier };
  const url = new URL(DBRIJ + '/oauth/authorize');
  url.search = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    response_type: 'code',
    scope: 'openid profile email',
    state,
    code_challenge: challenge,
    code_challenge_method: 'S256',
  }).toString();
  res.redirect(url.toString());
});

// 2. Dbrij sends them back with a one time code: check the state, swap the code.
app.get('/auth/dbrij/callback', async (req, res) => {
  const saved = req.session.dbrij;
  if (!saved || req.query.state !== saved.state) return res.status(400).send('Sign in expired, try again');
  if (req.query.error) return res.redirect('/login?cancelled=1'); // they pressed Cancel

  const token = await fetch(DBRIJ + '/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: String(req.query.code),
      redirect_uri: REDIRECT_URI,
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code_verifier: saved.verifier,
    }),
  }).then((r) => r.json());
  if (token.error) return res.status(401).send(token.error_description);

  // 3. Who signed in: sub is their permanent Dbrij id, key your user record on it.
  const me = await fetch(DBRIJ + '/oauth/userinfo', {
    headers: { Authorization: 'Bearer ' + token.access_token },
  }).then((r) => r.json());

  req.session.dbrij = undefined;
  req.session.user = { dbrijId: me.sub, name: me.name, email: me.email, picture: me.picture };
  res.redirect('/');
});

app.listen(3000);

Developer kit

Ready to copy, no package to install from Dbrij. Pick the one closest to your product. Every OpenID Connect library also sets itself up from the discovery address.

Discovery
https://api.dbrij.com/.well-known/openid-configuration
Next.js (App Router, on your server)
// app/auth/dbrij/start/route.ts
import crypto from 'node:crypto';
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';

const DBRIJ = 'https://api.dbrij.com/api';
const REDIRECT_URI = 'https://yourapp.com/auth/dbrij/callback'; // registered exactly

export async function GET() {
  const state = crypto.randomBytes(16).toString('base64url');
  const verifier = crypto.randomBytes(32).toString('base64url');
  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
  (await cookies()).set('dbrij_oauth', JSON.stringify({ state, verifier }), {
    httpOnly: true, secure: true, sameSite: 'lax', path: '/auth/dbrij', maxAge: 600,
  });
  const url = new URL(DBRIJ + '/oauth/authorize');
  url.search = new URLSearchParams({
    client_id: process.env.DBRIJ_CLIENT_ID!,
    redirect_uri: REDIRECT_URI,
    response_type: 'code',
    scope: 'openid profile email',
    state,
    code_challenge: challenge,
    code_challenge_method: 'S256',
  }).toString();
  return NextResponse.redirect(url);
}

// app/auth/dbrij/callback/route.ts
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';

const DBRIJ = 'https://api.dbrij.com/api';
const REDIRECT_URI = 'https://yourapp.com/auth/dbrij/callback';

export async function GET(req: Request) {
  const params = new URL(req.url).searchParams;
  const jar = await cookies();
  const saved = JSON.parse(jar.get('dbrij_oauth')?.value ?? 'null');
  jar.delete({ name: 'dbrij_oauth', path: '/auth/dbrij' });
  if (!saved || params.get('state') !== saved.state) return new Response('Sign in expired, try again', { status: 400 });
  if (params.get('error')) return NextResponse.redirect(new URL('/login?cancelled=1', req.url));

  const basic = Buffer.from(process.env.DBRIJ_CLIENT_ID + ':' + process.env.DBRIJ_CLIENT_SECRET).toString('base64');
  const token = await fetch(DBRIJ + '/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Authorization: 'Basic ' + basic },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: params.get('code') ?? '',
      redirect_uri: REDIRECT_URI,
      code_verifier: saved.verifier,
    }),
  }).then((r) => r.json());
  if (token.error) return new Response(token.error_description, { status: 401 });

  const me = await fetch(DBRIJ + '/oauth/userinfo', {
    headers: { Authorization: 'Bearer ' + token.access_token },
  }).then((r) => r.json());

  // Key your user on me.sub (their permanent Dbrij id), then start your own session.
  const res = NextResponse.redirect(new URL('/', req.url));
  res.cookies.set('session', await yourOwnSessionFor(me.sub, me.email), { httpOnly: true, secure: true, sameSite: 'lax' });
  return res;
}
React, browser only (PKCE, no secret)
// dbrij-auth.ts (a client made for a "browser only app": it has no secret)
const DBRIJ = 'https://api.dbrij.com/api';
const CLIENT_ID = 'dbrij_client_xxxxxxxx';
const REDIRECT_URI = window.location.origin + '/callback'; // registered exactly

const b64url = (bytes: ArrayBuffer | Uint8Array) =>
  btoa(String.fromCharCode(...new Uint8Array(bytes))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

// extra: more authorize parameters, such as { prompt: 'none' } for a silent check.
export async function signInWithDbrij(extra: Record<string, string> = {}) {
  const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
  const state = b64url(crypto.getRandomValues(new Uint8Array(16)));
  const challenge = b64url(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)));
  sessionStorage.setItem('dbrij_pkce', JSON.stringify({ verifier, state }));
  const url = new URL(DBRIJ + '/oauth/authorize');
  url.search = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    response_type: 'code',
    scope: 'openid profile email',
    state,
    code_challenge: challenge,
    code_challenge_method: 'S256',
    ...extra,
  }).toString();
  window.location.assign(url.toString());
}

export async function finishSignIn() {
  const params = new URLSearchParams(window.location.search);
  const saved = JSON.parse(sessionStorage.getItem('dbrij_pkce') ?? 'null');
  sessionStorage.removeItem('dbrij_pkce');
  if (!saved || params.get('state') !== saved.state) throw new Error('Sign in expired, try again');
  if (params.get('error')) throw new Error(params.get('error_description') ?? 'Sign in was cancelled');

  // No secret: the verifier proves this browser started the sign in.
  const token = await fetch(DBRIJ + '/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: params.get('code') ?? '',
      redirect_uri: REDIRECT_URI,
      client_id: CLIENT_ID,
      code_verifier: saved.verifier,
    }),
  }).then((r) => r.json());
  if (token.error) throw new Error(token.error_description);

  const me = await fetch(DBRIJ + '/oauth/userinfo', {
    headers: { Authorization: 'Bearer ' + token.access_token },
  }).then((r) => r.json());
  return { me, token }; // keep tokens in memory, not in localStorage
}

// App.tsx
import { useEffect, useState } from 'react';
import { finishSignIn, signInWithDbrij } from './dbrij-auth';

export function App() {
  const [me, setMe] = useState<{ sub: string; name: string; email: string } | null>(null);
  useEffect(() => {
    if (window.location.pathname !== '/callback') return;
    finishSignIn().then(({ me }) => {
      setMe(me);
      window.history.replaceState(null, '', '/');
    });
  }, []);
  return me ? <p>Signed in as {me.name}</p> : <button onClick={signInWithDbrij}>Sign in with Dbrij</button>;
}
React Native with Expo (PKCE and your own scheme)
// npx expo install expo-auth-session expo-crypto expo-web-browser expo-secure-store
// app.json: { "expo": { "scheme": "com.yourapp.mobile" } }
// Register this redirect address on a "phone app" client: com.yourapp.mobile:/callback
import { useEffect } from 'react';
import { Button } from 'react-native';
import * as AuthSession from 'expo-auth-session';
import * as SecureStore from 'expo-secure-store';
import * as WebBrowser from 'expo-web-browser';

WebBrowser.maybeCompleteAuthSession();

const DBRIJ = 'https://api.dbrij.com/api';
const CLIENT_ID = 'dbrij_client_xxxxxxxx'; // no secret in the app, ever
const discovery = {
  authorizationEndpoint: DBRIJ + '/oauth/authorize',
  tokenEndpoint: DBRIJ + '/oauth/token',
  revocationEndpoint: DBRIJ + '/oauth/revoke',
};
const redirectUri = AuthSession.makeRedirectUri({ native: 'com.yourapp.mobile:/callback' });

export function SignInWithDbrij({ onSignedIn }: { onSignedIn: (me: { sub: string; name: string }) => void }) {
  // PKCE (S256) and state are made and checked for you.
  const [request, response, promptAsync] = AuthSession.useAuthRequest(
    { clientId: CLIENT_ID, redirectUri, scopes: ['openid', 'profile', 'email'], usePKCE: true },
    discovery,
  );

  useEffect(() => {
    if (response?.type !== 'success' || !request?.codeVerifier) return;
    AuthSession.exchangeCodeAsync(
      { clientId: CLIENT_ID, code: response.params.code, redirectUri, extraParams: { code_verifier: request.codeVerifier } },
      discovery,
    ).then(async (tokens) => {
      if (tokens.refreshToken) await SecureStore.setItemAsync('dbrij_refresh', tokens.refreshToken);
      const me = await fetch(DBRIJ + '/oauth/userinfo', {
        headers: { Authorization: 'Bearer ' + tokens.accessToken },
      }).then((r) => r.json());
      onSignedIn(me);
    });
  }, [response]);

  return <Button title="Sign in with Dbrij" disabled={!request} onPress={() => promptAsync()} />;
}

How it works

Let people sign into your product with their Dbrij account: standard OAuth 2.0 authorization code flow, the same shape as any standard social sign in. Turn it on per app in Dbrij Auth, under Sign in with Dbrij: register your redirect URIs and you get a client_id plus a client_secret (shown once). Your app's name is what the consent screen shows.

The flow. 1 · Send the person to the authorize URL. 2 · They approve on the Dbrij consent screen and come back to your redirect_uri with a one time code (and your state). 3 · Exchange the code server side for tokens. 4 · Read the profile from userinfo. PKCE (S256) is supported and recommended.

1 · Send them to authorize
https://api.dbrij.com/api/oauth/authorize
  ?client_id=dbrij_client_xxxxxxxx
  &redirect_uri=https://yourapp.com/auth/dbrij/callback
  &response_type=code
  &scope=profile%20email
  &state=a-random-string-you-verify-later
2 · They come back with a code
https://yourapp.com/auth/dbrij/callback?code=dbrij_code_…&state=a-random-string-you-verify-later
3 · Exchange it (server side)
curl -X POST https://api.dbrij.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=dbrij_code_… \
  -d redirect_uri=https://yourapp.com/auth/dbrij/callback \
  -d client_id=dbrij_client_xxxxxxxx \
  -d client_secret=dbrij_cs_xxxxxxxx

# → { "access_token": "dbrij_cat_…", "token_type": "Bearer", "expires_in": 3600,
#     "refresh_token": "dbrij_crt_…", "scope": "profile email" }
4 · Read who signed in
curl https://api.dbrij.com/api/oauth/userinfo \
  -H "Authorization: Bearer dbrij_cat_…"

# → { "sub": "b1f2…", "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe",
#     "preferred_username": "jane", "picture": "https://…",
#     "email": "jane@dmyil.com", "email_verified": true }

Scopes

openidscopeOpenID Connect: the token response also carries an ID token saying who signed in. Ask for it with profile and email to have those claims in it.
profilescopeName, username and photo. Included in the default scope.
emailscopeThe verified email on the account. Included in the default scope.
hosting:read and the other data scopesreviewedData beyond who someone is. Your app may ask for these only after Dbrij approves it: ask for a review in Dbrij Auth. Until then authorize refuses them. Their tokens work on the Dbrij MCP server only.

OpenID Connect

Ask for openid and the code exchange returns an id_token as well: a JWT signed RS256 by Dbrij, carrying iss, sub (the account id), aud (your client id), auth_time, at_hash, the nonce you sent to authorize, and the profile and email claims your scopes name. Any OpenID Connect library sets itself up from the discovery document, and verifies tokens with the keys in the JWKS. The signing key changes every 90 days: the next key is in the JWKS a day before it signs, and the old one stays two days after, so a library that refetches the JWKS on an unknown kid never misses a beat. Refreshing does not return a new ID token.

Discovery and keys
https://api.dbrij.com/.well-known/openid-configuration
https://api.dbrij.com/.well-known/jwks.json

# authorize with:  &scope=openid%20profile%20email&nonce=a-random-string
# the exchange then returns:  { "access_token": "…", "id_token": "eyJhbGciOiJSUzI1NiIs…", … }

Ask more of the sign in

For a bank, an admin console or anything sensitive, the authorize request can ask for more than a signed in person. The ID token, and userinfo when you asked for openid, then say what happened, so check them on your side too.

A fresh sign in, two step, and who to expect
https://api.dbrij.com/api/oauth/authorize
  ?client_id=dbrij_client_xxxxxxxx
  &redirect_uri=https://yourapp.com/auth/dbrij/callback
  &response_type=code
  &scope=openid%20profile%20email
  &state=…&nonce=…&code_challenge=…&code_challenge_method=S256
  &prompt=login                       # confirm it is you now, even if signed in
  &max_age=900                        # or: signed in within the last 15 minutes
  &acr_values=urn:dbrij:acr:mfa       # two step required
  &login_hint=ada@yourcompany.com     # start the Dbrij sign in with this filled in

# The ID token (and userinfo) then say how the person signed in:
# { "auth_time": 1763726400, "amr": ["pwd", "otp", "mfa"], "acr": "urn:dbrij:acr:mfa", … }
prompt=loginauthorizeThe person confirms it is you again (password, authenticator code or an emailed code), even if they are signed in.
prompt=consentauthorizeShow the consent screen even if the person approved your app before.
prompt=noneauthorizeShow nothing at all. See silent sign in checks below. It cannot be combined with another prompt value.
max_agesecondsIf they last proved who they are longer ago than this, they confirm it is you first. Compare auth_time yourself as well.
acr_valuesurn:dbrij:acr:mfaTwo step required: an authenticator code, a phone approval or a passkey. Someone without two step is shown how to set it up, or comes back with error=unmet_authentication_requirements.
login_hintemail or handleStarts the Dbrij sign in screen with this filled in. Only a hint: the person can change it.
auth_timeclaimWhen the person last proved who they are (seconds since 1970).
amrclaimHow: pwd (password), otp (a one time code), hwk (a passkey), mca (approved on their phone), mfa (two step). Absent when unknown, such as a sign in through another provider.
acrclaimurn:dbrij:acr:mfa after two step, urn:dbrij:acr:basic otherwise.

Silent sign in checks

Add prompt=none to ask whether the person is already signed in to Dbrij and has already allowed your app, without showing them anything. Dbrij sends them straight back to your redirect address with your state and iss: with a code when they are signed in and have allowed every scope you ask for, or with one of the errors below. A silent check never grants anything new. max_age and acr_values still apply.

Use a top level redirect, such as on page load. Dbrij does not load inside a frame on another site, and browsers block the third party cookies and storage a hidden frame would need, so a frame would only ever answer signed out. Check once per visit: every answer comes back to your callback. A server app does the same by adding prompt=none to the address its start route redirects to.

Check on page load in a browser app
// silent-check.ts, beside dbrij-auth.ts from the browser app example
import { finishSignIn, signInWithDbrij } from './dbrij-auth';

// What a silent check answers when it cannot sign the person in without them.
const NOT_YET = ['login_required', 'consent_required', 'interaction_required'];

export async function checkSignedIn(): Promise<{ sub: string; name: string } | null> {
  if (window.location.pathname === '/callback') {
    const error = new URLSearchParams(window.location.search).get('error');
    if (error && NOT_YET.includes(error)) {
      // Not signed in to Dbrij, not allowed yet, or two step needed: show your button.
      sessionStorage.removeItem('dbrij_pkce');
      window.history.replaceState(null, '', '/');
      return null;
    }
    const { me } = await finishSignIn(); // a code: signed in, swap it as usual
    window.history.replaceState(null, '', '/');
    return me;
  }
  // Once per visit. Every answer comes back to /callback, so asking again would loop.
  if (sessionStorage.getItem('dbrij_checked')) return null;
  sessionStorage.setItem('dbrij_checked', '1');
  await signInWithDbrij({ prompt: 'none' }); // a top level redirect; Dbrij shows nothing
  return null;
}
codeanswerSigned in, and every scope was allowed before. Swap it as usual. The ID token says when and how they signed in.
login_requirederrorNobody is signed in to Dbrij in this browser, or the sign in is older than your max_age. Show your Sign in with Dbrij button.
consent_requirederrorSigned in, but they have not allowed every scope you ask for, or a scope still waits for Dbrij review. Send them through the normal sign in.
interaction_requirederrorSigned in, but they must do something first, such as two step for acr_values. Send them through the normal sign in.
invalid_requesterrorprompt=none came with another prompt value, or the request was missing something, such as PKCE for a browser app.

Refresh and revoke

Access tokens live one hour. Refresh with grant_type=refresh_token at the same token endpoint; each refresh token works once and the response carries its replacement. A rotated out refresh token presented again is treated as a leak: every token for that account and app is revoked on the spot. Revoke a token yourself with POST /oauth/revoke (body field token).

The rules that keep it safe

redirect_uriexact matchMust equal a registered URI character for character, at authorize AND at exchange. https only (localhost may use http). A phone or desktop app may also use its own scheme (com.example.app:/callback) or http://127.0.0.1 on any port.
codeone minute, one useExchange it immediately, server side. A second exchange fails and always verify state.
client_secretserver onlyNever ship it in a browser or app binary. A phone, desktop or browser only app is made without a secret and must use PKCE: code_challenge (S256) on authorize, code_verifier on exchange.
rate limits429The token endpoint allows 600 requests a minute per client, userinfo 120 a minute per access token, revoke 120 a minute per address. Normal refresh traffic stays well inside.
errorsRFC 6749The token endpoint answers the spec shapes: { "error": "invalid_grant", "error_description": "…" } with 400/401, not the platform envelope.

People manage what they have connected under Settings, then Security, then Connected apps. Disconnecting there revokes every token your app holds for them, so treat a 401 from userinfo as "signed out".

Test your setup

  1. Discovery opens. The discovery address loads and names the issuer your library expects.
  2. Redirect matches exactly. Scheme, host, path and trailing slash all match a registered address. A near miss is refused, never fixed.
  3. The consent screen looks right. Your name, logo and links show. Ask Dbrij to review your app to drop the not reviewed badge.
  4. Cancel works. Press Cancel once: your callback gets error=access_denied with your state, and says so kindly.
  5. State is checked. A callback whose state is not the one you saved is refused.
  6. Codes work once. Swap the same code twice: the second answer is invalid_grant. Swap within a minute.
  7. Key users on sub. sub is the permanent Dbrij id. Emails can change; sub never does.
  8. ID token verified. Check the signature with the JWKS, iss, aud equal to your client id, exp, and your nonce.
  9. Refresh rotates. Keep only the newest refresh token. Sending an old one revokes every token for that person.
  10. Disconnect means signed out. Disconnect your app from Settings, then Security. userinfo answers 401: treat it as signed out.
  11. No secret in apps. A phone, desktop or browser app has no secret and uses PKCE S256 on every sign in.
  12. Two step, if you require it. Send acr_values=urn:dbrij:acr:mfa and check acr in the ID token before you let anyone in.
  13. Silent checks, if you use them. Send prompt=none once per visit as a top level redirect. login_required, consent_required and interaction_required all mean: show your button.

Media & uploads

Attach images, video, audio and files to any message. You have two options:

1 · Bring your own URL. If you already host the file, just include it in attachments when sending a message, no upload step needed.

2 · Upload to Dbrij storage. Request a signed direct upload, send the file straight to storage (the bytes never touch your server), then attach the returned URL.

POST/uploads/signchat:write

Sign an upload

Returns a one time signed payload to upload a single file directly to Dbrij storage.

PATH / BODY PARAMETERS

kind*'image' | 'video' | 'audio' | 'file'The media kind.
Request
curl -X POST https://api.dbrij.com/api/uploads/sign \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "image" }'
Request body
{ "kind": "image" }
Response 200
{
  "success": true,
  "data": {
    "cloudName": "dbrij",
    "apiKey": "8123…",
    "timestamp": 1751200000,
    "signature": "a1b2…",
    "folder": "dbrij/apps/<app>/attachments",
    "resourceType": "image",
    "uploadUrl": "https://api.cloudinary.com/v1_1/dbrij/image/upload"
  }
}

With the SDK it's one call:

Upload + send (browser)
// 'file' is a browser File (e.g. from an <input type="file">)
const attachment = await dbrij.uploadMedia('image', file);

await dbrij.sendMessage(convo.id, {
  author: { externalUserId: 'user_42' },
  body: 'Check this out',
  attachments: [attachment],
});

Or upload yourself, then attach the URL:

Manual upload (any language)
# 1) POST the file to uploadUrl with the signed fields:
curl -X POST "$UPLOAD_URL" \
  -F "file=@./photo.jpg" \
  -F "api_key=$API_KEY" -F "timestamp=$TIMESTAMP" \
  -F "signature=$SIGNATURE" -F "folder=$FOLDER"
# → response has "secure_url", "width", "height", "bytes"

# 2) Send a message referencing it:
curl -X POST https://api.dbrij.com/api/conversations/$CONVO_ID/messages \
  -H "Authorization: Bearer $DBRIJ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "author": { "externalUserId": "user_42" }, "body": "",
        "attachments": [{ "name": "photo.jpg", "kind": "image", "url": "<secure_url>" }] }'

ATTACHMENT FIELDS

name*stringFile name shown in the UI.
kind*'image'|'video'|'audio'|'file'Media kind (drives how clients render it).
url*stringThe media URL (yours or from the upload).
sizeLabelstringe.g. "2.1 MB".
durationMsnumberLength for audio/video.
mimeTypestringe.g. "image/png".
width / heightnumberPixels (image/video).
thumbnailUrlstringPoster image (video).

Realtime

Deliver messages, typing, read receipts and presence to your end users' devices live, without building your own fan out. Mint a short lived token for a user, connect to Dbrij over Socket.IO, and join their conversation rooms.

POST/realtime/tokenchat:read

Mint a realtime token

Returns a 1 hour token for one of your end users to connect to realtime.

Request
curl -X POST https://api.dbrij.com/api/realtime/token \
  -H "Authorization: Bearer $DBRIJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "user_99" }'
Request body
{ "externalUserId": "user_99" }
Response 200
{
  "success": true,
  "data": {
    "token": "eyJhbGciOi…",
    "expiresIn": 3600,
    "events": ["message", "message:update", "typing", "conversation:read", "presence"]
  }
}

Connect from your client

Browser (socket.io-client)
import { io } from 'socket.io-client';

const { token } = await dbrij.realtimeToken({ externalUserId: 'user_99' });

// Connect to the Dbrij API host (same host as your REST base).
const socket = io('https://api.dbrij.com', { auth: { token } });

socket.on('connect', () => {
  socket.emit('join', { channel: 'conversation', id: CONVERSATION_ID });
});

socket.on('message', (m) => console.log('new message', m));
socket.on('typing', (t) => console.log('typing', t));
socket.on('conversation:read', (r) => console.log('read', r));
socket.on('presence', (p) => console.log('presence', p));

// Tell others this user is typing:
socket.emit('typing', { conversationId: CONVERSATION_ID, typing: true });

EVENTS YOU RECEIVE

messageMessageA new message in a joined conversation.
message:updateMessageA message was edited or its reactions changed.
typing{ conversationId, userId, typing }Someone is typing.
conversation:read{ conversationId, userId, at }A read receipt.
presence{ conversationId, userId, online }A member came online / went offline.

The token authenticates exactly one of your end users and expires in 1 hour, so mint a fresh one per session. Joining a conversation requires that user to be a member.

Webhooks

Set a webhook URL on your app in the dashboard. Dbrij POSTs a signed JSON envelope for each event. Because your end users don't connect to Dbrij directly, message.created is how you deliver chat to their clients.

Envelope
{
  "id": "evt_…",
  "type": "message.created",
  "createdAt": "2026-06-29T12:05:00.000Z",
  "data": { … }
}

Events

meeting.startedA meeting goes live.
data
{ "meetingId": "b1f2…" }
meeting.endedA meeting ends (host ended it, or the room emptied).
data
{ "meetingId": "b1f2…" }
meeting.participant.joinedAn end user joins the call.
data
{ "meetingId": "b1f2…", "externalUserId": "user_99" }
meeting.participant.leftAn end user leaves the call (carries metered minutes).
data
{ "meetingId": "b1f2…", "externalUserId": "user_99", "minutes": 12 }
recording.readyA recording finished processing.
data
{ "meetingId": "b1f2…", "recordingUrl": "https://…" }
message.createdA message is sent in one of your conversations.
data
{ "conversationId": "c7a1…", "message": { "id": "m9c2…", "authorExternalUserId": "user_42", "body": "…" } }
support.ticket.createdA ticket your app opened was created.
data
{ "ticketId": "t9d1…", "reference": "ACME-42", "status": "open" }
support.ticket.repliedThe team (or Deputy) replied to the customer. Send your app’s push from here: it names the customer and carries the opening line.
data
{ "ticketId": "t9d1…", "reference": "ACME-42", "status": "waiting_on_customer", "channel": "widget", "contact": { "externalId": "user_42", "email": "ada@example.com" }, "preview": "Clear your cache and…" }
support.ticket.resolvedThe team marked the fix in place; the customer is asked to confirm.
data
{ "ticketId": "t9d1…", "reference": "ACME-42", "status": "resolved" }
support.ticket.confirmedThe customer confirmed the fix.
data
{ "ticketId": "t9d1…", "reference": "ACME-42", "status": "closed" }
support.ticket.closedThe ticket closed.
data
{ "ticketId": "t9d1…", "reference": "ACME-42", "status": "closed" }

Verify the signature

Each delivery includes X-Dbrij-Signature: sha256=…, an HMAC of the raw request body using your app's signing secret (rotate it in the dashboard). Verify before trusting a payload.

Node
import { createHmac } from 'crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return header === expected; // compare to X-Dbrij-Signature
}

Objects

The response shapes you'll work with.

Meeting

shape
{
  "id": "string",
  "status": "scheduled | live | ended | cancelled",
  "mode": "video | voice",
  "title": "string",
  "code": "string | null",          // short join code people type to join
  "scheduledFor": "string | null",
  "startedAt": "string | null",
  "endedAt": "string | null",
  "participantCount": "number?",    // present on GET /meetings/:id
  "isRecorded": "boolean",
  "recordingUrl": "string | null",
  "createdAt": "string"
}

Conversation

shape
{
  "id": "string",
  "type": "direct | group",
  "title": "string",
  "memberCount": "number?",         // present on GET /conversations/:id
  "members": "Member[]?",
}
// Member: { "externalUserId": string, "name": string, "avatarUrl": string | null }

Message

shape
{
  "id": "string",
  "conversationId": "string",
  "authorExternalUserId": "string | null",
  "body": "string",
  "attachments": "Attachment[]",
  "createdAt": "string",
  "parentMessageId": "string | null",
  "reactions": "{ emoji: string, count: number }[]"
}
// Attachment: { id, name, kind: 'image'|'video'|'audio'|'file', url, sizeLabel?, durationMs?, mimeType?, width?, height?, thumbnailUrl? }

Token response

shape
{ "url": "string (wss://…)", "token": "string (JWT)", "identity": "string", "meeting": Meeting }

Errors & limits

Errors use standard HTTP status codes with a JSON body:

401UnauthorizedMissing, invalid, revoked or expired API key.
403ForbiddenKey missing a required scope, acting on another app, or email-unverified (live keys / billing).
404Not FoundUnknown meeting, conversation, message, or external user.
402Payment RequiredMonthly request allotment exhausted on the free tier. Upgrade in the dashboard.
429Too Many RequestsExceeded your plan's per minute rate ceiling.
422 / 400ValidationMalformed body or invalid field.
Error shape
{
  "success": false,
  "statusCode": 403,
  "message": "API key is missing required scope(s): meetings:write",
  "error": "Forbidden",
  "path": "/api/emails",
  "timestamp": "2026-08-06T22:56:17.969Z"
}

message is a sentence for a person; error is the stable status name, useful for branching. path and timestamp identify the request when you report a problem.

Meetings and Chat are optional add-ons, each turned on and paid for in its own product (Meetings → API, Chat → API): call minutes and meetings, or messages, are counted against that add-on's plan. Keys made in Developer before keep their Developer plan. The Support API comes with Resolve and is never metered against a plan.

Dbrij is Nigeria’s company operating system: the first Nigerian built platform to put team chat, video meetings, email, HR, tax compliant payroll, customer support, marketing, analytics and cloud hosting in one product on one subscription.

Everything on Dbrij

More from Dbrij