Local development

Goal

Build and debug your integration from your own machine. You call the production Chat API with a test tenant of your own, you decode tokens locally to see why a call fails, and you check each piece with curl before you write code.

Prerequisites

• A backend client and the values from the checklist.
• Node.js 20 or later for the token one-liner, plus curl and jq.

Set up a test tenant

You develop against the production Chat API, https://chat.centralcodestation.com/api/v1. Use a Tenant of your own for development, for example fitness-test, with its own tenant application, backend client, roles and a few test users such as coach-ana and client-john. Keep real users and real conversations out of it.

1. Create the test tenant and application in the Identity Server admin UI (or ask your operator for them), and switch Chat on for the application.

2. Register a backend client for it and keep its values in a local .env file that is never committed. See Register a backend client.

3. Allow your dev origin. For a web app on your machine, add http://localhost:<port> to Allowed Origins of the SPA client. The Identity Server accepts localhost origins only on a development application. See Register web origins.

4. Grant Chat permissions to the test roles inside the application. See Grant permissions to roles.

CCS_ISSUER_URL=https://auth.centralcodestation.com
CHAT_API_URL=https://chat.centralcodestation.com/api/v1
CHAT_API_RESOURCE=https://chat.centralcodestation.com/api

The interactive API explorer is not available on the public site. Use the API reference and curl.

Inspect a token

Most failures are in the token. Decode it locally and read the claims.

node -e 'const p=process.argv[1].split(".")[1];console.log(JSON.parse(Buffer.from(p,"base64url")))' "$TOKEN"

Danger

Decode tokens on your machine. Never paste a token into an online decoder or a shared tool: a valid token is a credential until it expires.

Claim	Expect	If it is wrong
aud	chat-api	401 invalid_token. The token was requested for your own API, or with the audience instead of the resource identifier.
scope	Machine token: chat:sync or the granular scopes. User token: chat:access.	403 insufficient_scope.
client_id	Your backend client, for machine tokens and for exchanged user tokens. It must belong to the tenant application in the URL.	403 client_context_mismatch.
sub	Machine token: equal to client_id. User token: the user’s id.	403 principal_not_allowed or 400 user_required on a route for the other kind.
exp	A time in the future	401 invalid_token.
act	Present on an exchanged token, absent on a machine token	The token came from the wrong grant.

Chat reads no tenant claim. The tenant and application come from the URL, and Chat checks them against the client in the token.

Smoke tests with curl

Run these in order. Each one proves a layer, so a failure tells you where to look.

# 1. A machine token. Decode it and check aud and scope.
CHAT_TOKEN=$(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" | jq -r .access_token)

# 2. The Chat API accepts it and your context is right.
curl -s "$CHAT_API_URL/tenants/$CCS_TENANT_ID/applications/$CCS_APPLICATION_ID/conversations" \
  -H "Authorization: Bearer $CHAT_TOKEN"

{ "items": [], "next_cursor": null }

An empty items list is a pass: the token, the audience, the scope and the context all work. Then create a conversation as in Create direct conversations, and test the user side with an exchanged token against GET .../me/capabilities as in Issue Chat tokens to your users.

Verify

Step 2 above answers 200 with the items list, your test users can be added to a conversation, and the decoded user token shows aud chat-api and scope chat:access.

Troubleshooting

Symptom	Cause and fix
The token request answers invalid_target	resource is not the identifier. Use https://chat.centralcodestation.com/api.
401 invalid_token	Check aud and exp first.
403 client_context_mismatch	CCS_TENANT_ID or CCS_APPLICATION_ID is not your client’s own tenant application.
404 application_not_found	The application id is wrong, or Chat is not enabled for it.
A browser call fails but curl works	CORS: the page’s origin is not on the SPA client. See Register web origins.
More help	Troubleshooting

Related

• Register a backend client
• Issue Chat tokens to your users
• Identity and tokens
• Limits