Skip to content
CCS Chat Docs

Prerequisite checklist

Work through this checklist once for each Tenant application. You need only this page and the Identity Server admin UI (the application at admin.centralcodestation.com). Each step says where to click, links to the guide with more depth, and ends with a check.

Standalone or integrated

Section titled “Standalone or integrated”

Steps 1 to 3, 8 and 9 apply to both product modes. Steps 4 to 7 apply only to Integrated use, where your code calls Chat. In Standalone use, your people sign in at chat.centralcodestation.com with their Identity Server account and you create no clients. See Choose how to use Chat.

Step Standalone Integrated
1. Tenant and members yes yes
2. Your tenant application yes yes
3. Chat enabled yes yes
4. Chat API resource operated by CCS operated by CCS
5. Backend client no yes
6. Token exchange no yes, for web apps
7. Web origins no yes, for web apps
8. Application roles yes yes
9. Chat permissions yes yes
10. Values you need no yes

The steps

Section titled “The steps”

  1. A tenant exists and your users are members of it.

    In the Identity Server admin UI, open Tenants, pick your tenant and open Members. If the application only admits assigned users, assign each user to it as well. Without access Chat answers not_tenant_member or no_application_access.

    Verify: a member can sign in to the Identity Server.

  2. Your tenant application exists in that tenant.

    Chat is a Platform application and is never one of your applications. Conversations live inside yours, for example the Fitness app. Create it under Applications if it does not exist.

    Verify: the application is listed for the tenant and is ACTIVE.

  3. Chat is enabled for your application.

    Chat is available to every tenant application unless a tenant admin switched the Chat platform application off for it. A tenant admin can switch Chat off for a single application in the Identity Server admin UI, so check that it has not been.

    Verify: the Chat app’s workspace screen lists your application as selectable. Or call the API with the backend client token from step 5, stored in CHAT_TOKEN:

    Terminal window
    curl -s "$CHAT_API_URL/tenants/$CCS_TENANT_ID/applications" \
      -H "Authorization: Bearer $CHAT_TOKEN"
    # {"items":[{"application_id":"fitness-app","name":"Fitness App","type":"TENANT","chat_enabled":true, ...}]}

  4. The Chat API resource is registered.

    Central Code Station operates this for you; you do not create it. Its values are fixed, and you need them in your configuration. Clients send the identifier as resource=. Only Chat reads the audience, in the token’s aud claim.

    Value Setting
    Identifier (resource=) https://chat.centralcodestation.com/api
    Audience (aud) chat-api
    Scopes chat:access, chat:sync, chat:conversations.read, chat:conversations.manage, chat:groups.manage, chat:channels.manage, chat:messages.send, chat:users.lookup

    Never send chat-api as resource=: the Identity Server finds the resource by its identifier. See Identity and tokens.

    Verify: step 5 returns a token whose aud is chat-api.

  5. A backend client on your application. (integrated)

    In Clients, pick your application and create a client such as “Fitness Chat Backend”. Set it to CONFIDENTIAL and tick the grant types client_credentials and token-exchange (RFC 8693). Then open Resource Permissions, pick the Chat API resource and grant chat:sync, or only the granular scopes it needs. Open Permissions, then Token exchange, pick the Chat API as target resource and tick chat:access. Keep the secret on your server. Never ship it to a browser. See Register a backend client and Choose Chat scopes.

    Verify: a client_credentials call returns a token whose aud is chat-api.

    Terminal window
    curl -s -X POST "$CCS_ISSUER_URL/oauth/token" -u "$CCS_CHAT_SYNC_CLIENT_ID:$CCS_CHAT_SYNC_CLIENT_SECRET" \
      --data-urlencode "grant_type=client_credentials" \
      --data-urlencode "scope=chat:sync" \
      --data-urlencode "resource=$CHAT_API_RESOURCE" > token.json
    jq -r '.access_token | split(".")[1] | @base64d | fromjson | {aud, scope}' token.json
    # { "aud": "chat-api", "scope": "chat:sync" }

  6. Token exchange is enabled. (integrated, web and mobile apps)

    Token exchange is an Identity Server setting that its operator turns on. It is off by default. Ask your operator, or read Enable token exchange. The client from step 5 needs the grant type and the Token exchange permission for chat:access. Both are separate from its Resource Permissions.

    Verify: exchanging a user’s token returns a user token. The answer is not unsupported_grant_type.

  7. Your web app’s origin is registered. (integrated, web apps)

    Add the origin of your web app, for example https://app.fitness.example, to allowed_origins of your application’s web (SPA) client in the admin UI. Chat reads it from there and admits your origin. Nothing is configured on the Chat side, and a new origin works within about a minute. See Register web origins.

    Verify: a browser call from your origin to GET /tenants/{tenant_id}/applications/{application_id}/me/capabilities passes the CORS check.

  8. Application roles exist and are assigned.

    In the admin UI open Roles, pick your application and create the roles your product needs, for example coach and client. Assign them to users as you do today.

    Verify: your application roles are listed in Chat Administration under Roles & permissions once you pick your application.

  9. Chat permissions are mapped to those roles inside your application.

    Sign in to Chat as the tenant owner, or as an admin with administration.manage. Open Administration, then Roles & permissions, and pick your application. Every role starts with no permissions. For backend-driven conversations, grant conversations.read, messages.read, messages.send and messages.update. Leave out conversations.create, groups.create and users.lookup, so conversations start only through your backend. See Grant permissions to roles.

    Verify: GET /tenants/{tenant_id}/applications/{application_id}/me/capabilities with a user’s token lists the permissions you granted. In the SDK, call chat.capabilities().

  10. Collect the values your code needs.

    See the table below.

Values you need

Section titled “Values you need”

Keep these in your configuration. The names are the suggested convention for backend environment variables; the SDKs read no variables themselves.

Value Convention Example or source
Issuer URL CCS_ISSUER_URL https://auth.centralcodestation.com, the bare origin with no /api
Backend client id CCS_CHAT_SYNC_CLIENT_ID From step 5
Backend client secret CCS_CHAT_SYNC_CLIENT_SECRET From step 5. Server-side only
Tenant id CCS_TENANT_ID The Identity Server tenant id
Application id CCS_APPLICATION_ID The id of your tenant application from step 2
Chat API URL CHAT_API_URL https://chat.centralcodestation.com/api/v1
Chat API resource identifier CHAT_API_RESOURCE https://chat.centralcodestation.com/api

A web app needs only public values: the Chat API URL, the tenant id, the application id and the URL of your backend’s token route. It needs no OAuth client id, issuer URL or redirect URI for Chat.

Next steps

Section titled “Next steps”