Skip to main content
Create an API credential for the intended workspace in Developer, then send it in the x-chatobserver-key header or as a bearer token. Keep credentials on your server or in your integration’s secret store. The public API is served from https://app.chatobserver.com/api. Version 2 routes begin with /v2.

​
Validate a visibility API credential

Store your credential in the CHATOBSERVER_API_KEY environment variable, then run:
The response identifies the credential’s scopes, capabilities, and default project. Use /v2/projects to retrieve the associated project details. Bearer authentication is also supported:
Send one authentication method per request. If both headers are present, x-chatobserver-key takes precedence.

​
Choose the required scopes

Visibility read operations require read. Creating or modifying prompts, brands, tags, personas, or tracked coverage also requires write. Use a read-only credential for exports that do not need to change the workspace. The Data API requires a service-account credential and operation-specific metrics:* scopes. A visibility key with write does not automatically grant Data API access. The Reports API requires explicit reports:read or reports:write scopes. Service-account credentials act as their actual account and key, with current Report grants; they cannot borrow their creator’s permissions. Existing keys are not expanded automatically, and write does not imply read. Saved Data outputs additionally require metrics:read and independent query, connection and network access. Report ownership does not grant Data execution.

​
Keep workspace boundaries explicit

Credentials are workspace-scoped. An optional x-project-id header selects the matching project; it does not grant access to another workspace. Retrieve the project identifier from the API rather than constructing it from an organisation name. Never place a secret key in a public website, browser bundle, screenshot, or shared report. Revoke a credential when its integration no longer needs access.

​
Product access and delegated connections

A credential’s scope is only one part of authorisation. Workspace access, resource permissions and the availability of the requested feature also apply. Tracked coverage checks the same Sources and coverage availability policy as the dashboard. Workspace and service-account keys act as workspace credentials; creating one does not let the integration impersonate its creator. MCP connections carry separately approved permissions and selected workspaces. They can call only explicitly supported customer API operations. A new customer API endpoint does not automatically become available through MCP, and first-party dashboard endpoints and server actions are not part of the customer integration contract. Report stages, jobs, plans and receipts remain private to the exact account or delegated connection that created them. A second key for the same service account does not inherit the first key’s derived artifacts. Revocation, expiry and current permissions are checked again when reading, processing and committing work.