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: Bearer header with one of four kinds of token.

The four kinds of token

Signing in

The Colrows login page offers these methods:

• Username and password - a native Colrows account, or a directory (LDAP) account when your organization uses one. The REST equivalent is POST /api/user/login.
• Google and Microsoft - shown under or continue with when the host has them configured. Microsoft sign-in accepts work or school accounts and personal Microsoft accounts, unless the host restricts it to one Microsoft tenant.
• Log in with SSO - enter your company email and Colrows sends you to the SAML identity provider your organization administrator configured.

Colrows links a Google or Microsoft sign-in to that provider account, not to the email address. The first sign-in with a new provider account creates a new self-service Colrows account, the same as signing up (see Quickstart). If a Colrows account with the same email already exists, for example one created with a password or by an administrator, the Google or Microsoft sign-in is refused instead of being attached to it. When Cloudflare Turnstile is enabled on the server, password, Google, and Microsoft sign-in all need a valid Turnstile token.

Password reset

1. On the login page choose Forgot password?, enter your email, and choose Send reset link. The REST equivalent is POST /api/user/reset/password.
2. Open the link in the email within 15 minutes and set a new password of 8 to 128 characters. Each link works once.

Colrows gives the same response whether or not the account exists. Reset emails go only to active password accounts; Google, Microsoft, SAML, and LDAP users manage their password with their identity provider. Resetting or changing a password signs the user out of every session and cancels any other reset link still outstanding. A signed-in user changes their password in Settings → Password & Security.

REST API with a user session

Send the session token on every request:

Authorization: Bearer <session-token>

The browser keeps the session alive with a refresh token that lasts seven days and is replaced each time it is used; a refresh token that has already been used is rejected. Signing out ends the session. For unattended server-to-server calls, use an OAuth client instead.

Server-to-server with an OAuth client

A backend service calls Colrows with an OAuth client, not with a user's password. The client has its own identity and a fixed set of scopes:

1. An organization administrator creates the client in Administration → Settings → OAuth clients with Add OAuth client and the Server-to-server type, or with POST /api/sys/org/oauth-clients. Choose its scopes and an expiry date within one year. Copy the client secret straight away: Colrows shows it only once.
2. Your backend exchanges the client ID and secret for an access token. The ID and secret go in an HTTP Basic header on this request only:

   curl -X POST https://cloud.colrows.com/api/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=client_credentials \
     -d scope=semantic:read

3. Send the access_token from the response as a bearer token. It lasts 15 minutes and there is no refresh token, so request a new one before it expires.

If you leave out scope, the token gets every scope the client holds. Each operation in the REST API reference lists the scope it needs, and a token without that scope gets 403. An OAuth client runs queries only through the agent interface, and only with data:query; it can't use the AI analyst, dashboards, or chats. To revoke one access token, call POST /api/oauth/revoke with token=<access-token> and the client ID and secret in an HTTP Basic header. To revoke a client and every token it holds, choose Revoke in the same settings tab or call DELETE /api/sys/org/oauth-clients/{clientId}.

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.

Applications that act for your users

Your own application can use the same authorization-code flow to call the agent interface as each of its users, once an administrator registers it:

1. An organization administrator chooses Add OAuth client in Administration → Settings → OAuth clients with the Acts for users type, or calls POST /api/sys/org/oauth-apps. Give it a name users will see, 1 to 10 HTTPS callback URLs without a fragment, its scopes, and an expiry date within one year. Copy the client secret straight away: Colrows shows it only once.
2. Send each user to /oauth/authorize with PKCE (S256). Only users in the same organization can approve the app.
3. Exchange the code at POST /api/oauth/token with grant_type=authorization_code, and send the client ID and secret in an HTTP Basic header. Access tokens last 15 minutes; refresh tokens last 30 days and rotate on use.

The app can request semantic:read, semantic:sql, sql:execute, data:query, and data:sql, with the meanings in the table above. Every call runs as the user who approved it, with that user's data access and masking rules. Users see the apps they approved in Settings → Connected apps. Revoking the app ends every approval users gave it.

Agent interface

Your own agents call Colrows through the agent interface, either as MCP at POST /api/mcp/agents or as REST under /api/agents/v1. Discovery metadata is at /.well-known/oauth-protected-resource/api/mcp/agents. It accepts two kinds of token: an OAuth client access token (cr_sem_at_), which acts as the client, and an access token from an application an administrator registered (cr_mcp_at_), which acts as the user. Tokens from MCP clients that registered themselves, and user session tokens, are not accepted.

The MCP tool list shows only the tools your token's scopes allow. Every call still checks the principal's data access.