Docs: Authentication

Authentication

AI clients: OAuth

MCP clients sign in with OAuth 2.1 (authorization code with PKCE). CareChannel publishes protected-resource metadata for each workspace endpoint and authorization-server metadata at https://ballot.jumpstartsolutions.co/.well-known/oauth-authorization-server. Clients register with a Client ID Metadata Document, or dynamic registration for older clients. Tokens are bound to one workspace's endpoint, so a token for one workspace never works in another.

Team members and customers both sign in this way. The consent screen lists the toolsets (scopes) the client asks for; customers only ever get core.

Servers and scripts: API keys

Owners create API keys in the admin under API keys. A key acts as a service account with manager-level permissions, limited to the toolsets you tick, and never has owner-only powers. The secret (cc_sk_…) is shown once. Send it as Authorization: Bearer to REST, or to MCP for server-to-server use.

Acting for a customer

API keys and team members can record feedback for a customer: create_post, create_comment and add_vote_on_behalf take on_behalf_of (or user) with an email, external ID or user ID, and create the customer if they don't exist. The audit log shows who acted for whom.

Your own sign-in: Identify

To sign your customers in to the portal and widgets from your own app, sign a short-lived JWT (HS256) with the workspace's Identify secret, set up by an owner in the admin under Identify (SSO). Identify only signs people in to that workspace's portal, never to a CareChannel account.

Next: example apps that use an API key.