The Identity Server comes first

Chat does not have its own user accounts, sign-in or client registry. It runs on the CCS Identity Server, so you set that up before you call Chat. This page explains the split of responsibilities and points you to the checklist.

What the Identity Server owns

Everything about who people are and what they may reach lives in the Identity Server.

Owned by the Identity Server	What it means for Chat
Users and sign-in	A user signs in once. Chat never sees a password.
Tenants and memberships	A user can belong to several tenants. Chat only serves active members.
Roles	Tenant roles and your own application roles (coach, client). Chat maps them to Chat permissions.
Applications	Your tenant applications, and Chat itself as a platform application.
Clients	The OAuth clients that sign users in, and the backend client your server uses.
Scopes and resources	The Chat API is a resource with the scopes chat:access, chat:sync and the granular chat:* scopes.
Tokens	Every token Chat accepts is issued by the Identity Server, including the exchanged token your web app uses.

What Chat owns

Chat owns the conversation side and nothing else.

• Conversations, members, messages, reactions and read state.
• The mapping of roles to Chat permissions, separately for each application, edited in Chat Administration.
• Presence, realtime delivery and web push devices.
• The audit log of administration actions.

Chat stores no passwords and issues no tokens for your users. It also knows nothing about your business: a rule such as “a coach may message only their own clients” stays in your backend. See Architecture at a glance.

What Chat expects from it

Chat expects four things to be true at the Identity Server before a call can succeed.

1. A valid token for the Chat API. The token is signed by the Identity Server, has the audience chat-api and carries chat:access (users) or a Chat machine scope (backend clients). A token for your own API is rejected with invalid_token.
2. A context. Every call names a tenant and a tenant application in the URL. The user must be an active member of the tenant (not_tenant_member) and have access to the application (no_application_access).
3. A client bound to your application. A token issued to your application’s client works only in that application. Any other context answers client_context_mismatch.
4. Your web origins. The origins of your web app are read from your application’s client at the Identity Server. You configure nothing on the Chat side.

Read Identity and tokens for the token rules and Tenants and applications for the context.

Chat is not one of your applications

Chat is a platform application shared by all tenants. Conversations live inside your tenant application, and the Chat web app lists your applications once you pick a workspace (your tenant).

If the Identity Server is unavailable

Chat reuses recent answers from the Identity Server for a short time. When it cannot reach the Identity Server and has no recent answer, it responds with 503 identity_unavailable.

• Treat it as a temporary failure, not as a permission problem. Retry with a back-off.
• Your backend client and your web app also need the Identity Server to issue tokens, so new tokens fail during the same outage.
• Do not cache a failed token request for long: ask again after a short pause.

See Handle errors and retries for a retry pattern.

Where the Identity Server documentation lives

The Identity Server has its own documentation. Chat’s pages repeat every step you need to integrate, and link there for background and depth.

Identity Server documentationArchitecture, OAuth flows, clients, roles and the admin UI. Opens in a new tab.

Token exchangeSetup, the backend route, rules and troubleshooting for the exchange your web app depends on.

If a link does not open for you, ask your Identity Server administrator for access.

Next step

Work through the prerequisite checklist. It lists what to create in the Identity Server admin UI and how to verify each step. The glossary defines the terms.