Authentication

One reference for how every Colrows surface authenticates. The REST API is served under /api on your Colrows host (Colrows Cloud: https://cloud.colrows.com). Every protected request carries an Authorization header; the platform accepts three credential forms.

The three credential forms

REST API

Authenticate a REST call with a session bearer token obtained by logging in, then send it on every request:

Authorization: Bearer <session-token>

Organization API keys are not used directly as bearer tokens. An API key is a credential for the integration-login flow below, which exchanges it (with a user's credentials) for a session token.

Embedding & server-to-server (integration login)

To embed an assistant or dashboard, or to call Colrows from your own backend, exchange an organization API key plus a user's credentials for a session token:

POST https://cloud.colrows.com/api/integration/login
Content-Type: application/json

{ "userName": "svc-embed@acme.com", "pwd": "…", "apiKey": "<org-api-key>" }

Colrows validates the credentials and that the API key belongs to your organization and is active and unexpired, then returns a session token you use as the bearer for subsequent calls (and to mint embed tokens). Create and manage API keys in Administration. Public dashboards need no token. Full walkthrough: Embedded Assistants & Dashboards.

MCP clients & AI agents (OAuth 2.0 + PKCE)

ChatGPT, Claude, Cursor, Codex, the Excel add-in, and custom agents authenticate to the MCP connector with OAuth 2.0 - authorization-code grant with PKCE (S256) mandatory. Discover endpoints rather than constructing them:

/.well-known/oauth-protected-resource/api/mcp/mcp-clients
/.well-known/oauth-authorization-server/api/oauth

• Public clients (no client secret); dynamic client registration supported.
• Scopes: metadata:read and data:query.
• Access tokens (cr_mcp_at_…) are short-lived; refresh tokens (cr_mcp_rt_…) rotate on use.

The complete flow, scopes, and token lifetimes are in the MCP integration guide.