Skip to content
CCS Chat Docs

Register a backend client

Goal

Section titled “Goal”

Create the Backend client of your tenant application in the Identity Server admin UI. Your backend uses it to create conversations in Chat and, if your web app uses Chat, to give your users a Chat token. You do this once per tenant application.

Prerequisites

Section titled “Prerequisites”
  • A Tenant and a Tenant application in it, for example the tenant fitness with the application fitness-app. Chat is a Platform application: never create the client on Chat’s own application.
  • Chat is switched on for your application. See the prerequisite checklist.
  • Permission in the admin UI to manage your application’s clients. Ask your tenant owner if you do not have it.

Steps

Section titled “Steps”

  1. Open your tenant application. In the Identity Server admin UI, go to your tenant application, for example “Fitness”.

  2. Create the client. Open Clients and create a new client, for example “Fitness Chat Backend”. Set the type to CONFIDENTIAL. Enable the grant types client_credentials and token-exchange (RFC 8693). Chat needs only client_credentials; the token-exchange grant is for issuing Chat tokens to your users. Save, then copy the client id and the client secret.

  3. Grant it Chat scopes. Open the client, then Resource Permissions, then the Chat API resource. Tick chat:sync, or only the granular scopes your backend needs. See Grant Chat scopes.

  4. Allow it to exchange for chat:access. Open Permissions, then Token exchange, pick the Chat API as the target resource and tick chat:access. This is separate from Resource Permissions. See Enable token exchange. Skip it if no web or mobile app of yours calls Chat as the user.

  5. Store the values on your backend. Keep the secret in your secret store, never in a browser or a repository.

Name Value
CCS_ISSUER_URL The bare issuer origin, for example https://auth.centralcodestation.com (no /api)
CCS_CHAT_SYNC_CLIENT_ID The client id from step 2
CCS_CHAT_SYNC_CLIENT_SECRET The client secret from step 2
CCS_TENANT_ID Your tenant id
CCS_APPLICATION_ID Your tenant application id
CHAT_API_URL https://chat.centralcodestation.com/api/v1
CHAT_API_RESOURCE https://chat.centralcodestation.com/api, the Chat API Resource identifier

Use the resource identifier in resource=, never the Audience chat-api. The Identity Server looks the resource up by its identifier and writes the audience into the token as aud.

Verify

Section titled “Verify”

Request a machine token with curl.

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"

The response is JSON with access_token, token_type, expires_in and scope. Decode the token and check that aud is chat-api and scope contains chat:sync. Local development shows how.

Troubleshooting

Section titled “Troubleshooting”
Error Likely cause
invalid_client Wrong client id or secret, or the client is not CONFIDENTIAL.
unauthorized_client The client_credentials grant type is not enabled on the client.
invalid_scope The scope is not in the client’s Resource Permissions for the Chat API.
invalid_target resource is the audience (chat-api) or a typo. Use the identifier.

Chat answers client_context_mismatch when the token was issued to a client of another tenant or application than the one in the URL. A backend client works only in its own tenant application.

Section titled “Related”