Authentication
Channel API keys
Generate credentials under Project → Channels → API. Copy both values before saving. The API token authenticates your requests; the signing secret verifies callbacks from LogicDialog. They are different credentials and are not interchangeable.
Deploy the configuration to Live before testing. Include workspaceId, environment=live and integrationId on each message or history request. Requests from a different client cannot read or continue your conversations. A token is a server-side integration credential: keep it out of customer-facing JavaScript and mobile application bundles.
API keys cannot add knowledge, approve changes or deploy environments. Those operations currently require platform authentication. There is no channel-key knowledge upload endpoint or channel-key permission for publishing.
For outbound calls/SMS, select the permitted schedules by name under Allowed outbound schedules for the client. Existing keys have no outbound permission until explicitly granted. Clients used only for outbound contacts can leave message channels empty and do not require a reply webhook or signing secret. See the outbound examples in the workflows guide.
Platform authentication
Browser login starts at Sign in; the callback establishes a LogicDialog session. Server-side callers need a valid Kinde access token issued for the platform’s configured issuer/audience. Ask the platform administrator to provision the identity and workspace/organisation permissions. The API does not provide a channel-key-to-platform-token exchange or a public endpoint to mint management credentials.
The hosted explorer cannot reuse the parent application’s cookie. Select PlatformBearer and supply the authorised access token. Do not paste a Channels token, a Fern publishing token, or an AI provider API key into that field.
Common permissions are workspace.view for reading configuration, workspace.edit for editing/ingestion, conversations.review for staff history and Live Chat, and integrations.manage or workspace.manage for Channels. Applying a workstream needs both changes.approve and deploy.test or deploy.live, according to the destination.
Errors
- 400: invalid fields, missing branch, or an unsupported write to Live/main.
- 401: missing or invalid credentials. Check credential type as well as its value.
- 403: insufficient membership/permissions, disallowed channel or origin.
- 404: unavailable resource, including a conversation outside a client’s scope.
- 409: a pending message/delivery, conflicting message ID, ownership conflict or Git merge conflict. Follow the operation’s retry instructions.
- 422: deployment validation failed or unsupported transport content.
- 429: rate/pending-message limit exceeded.
Most application errors use error.code, error.message and a request ID; some channel routes return plain status text. Retain the x-request-id response header when asking for support.