Tenants and applications
Every Chat call runs in one context: a tenant plus one of its applications. Conversations, messages, permissions and live updates all belong to exactly one context, and nothing crosses from one to another.
Tenants and applications
Section titled “Tenants and applications”A tenant is an organisation in the Identity Server. The Chat UI calls it a workspace. A user can belong to several tenants.
An application is a product of that tenant, such as the Fitness app. There are two kinds:
| Example | Who uses it | |
|---|---|---|
| Tenant application | Fitness app | One tenant. Its users and its backend use Chat inside it. |
| Platform application | Chat itself | Every tenant. |
Chat is a platform application. It is never one of your applications and has no users of its own. Every conversation lives inside one tenant application; there is no tenant-wide or context-free conversation.
The context is in the URL
Section titled “The context is in the URL”Chat takes the tenant and the application only from the URL, never from a token claim or a request body:
/api/v1/tenants/{tenant_id}/applications/{application_id}/conversationsChat verifies the pair against the Identity Server on every call. The ids are the Identity Server’s ids for your tenant and application. A conversation of another tenant or application answers 404, as if it did not exist.
Switching Chat on for an application
Section titled “Switching Chat on for an application”An application can use Chat only when Chat is switched on for it. The Identity Server holds that switch as platform_access_enabled; the Chat API reports it as chat_enabled. The application list returns the applications the caller may use with Chat, plus the ones with chat_enabled: false, so a UI can show those as unavailable.
| What went wrong | Response |
|---|---|
| The tenant is not active, or Chat is off for it | 403 tenant_not_available |
| The user is not an active member of the tenant | 403 not_tenant_member |
| The application is unknown, or Chat is off for it | 404 application_not_found |
| The user has no access to the application | 403 no_application_access |
An administrator switches Chat on in the Identity Server admin UI: see Switch Chat on.
Users in several tenants
Section titled “Users in several tenants”A user who belongs to two tenants has two separate Chat contexts. Being a member of tenant B never gives access to tenant A’s conversations.
Which contexts a caller may use depends on the token:
- A token issued to Chat’s own web client works in every context the user belongs to.
- A token issued to a client of your tenant application works only in that application. Anything else answers 403
client_context_mismatch. This holds for tokens obtained by token exchange too. - A machine token is bound to its client’s tenant and application, and the application list shows it that one application only.
So a multi-tenant app takes the tenant from the signed-in user and uses one client and one SDK instance per context. See Multi-tenant apps.
Tenant-level and application-level routes
Section titled “Tenant-level and application-level routes”Most routes belong to an application. A few belong to the tenant, because they describe a person or the tenant rather than one application:
| Level | Routes | Why |
|---|---|---|
| Application | Conversations, messages, read state, typing, user lookup, realtime token, the caller’s permissions | Everything about a conversation lives in one application. |
| Tenant | The application list, the caller’s tenant-level permissions, presence, push devices, Chat Administration | Presence and push devices belong to a person in a tenant, so one registration serves every application. Administration manages the tenant. |
The tenant-level routes are under /api/v1/tenants/{tenant_id}/… with no application. See Presence and Push notifications.
Permissions are per application
Section titled “Permissions are per application”A tenant maps Chat permissions to roles separately for each application. Nothing inside the Fitness app is inherited from another application or from the tenant-wide mapping. See Chat permissions.