Authentication

Recommended auth choices

Use case	Recommended method
Server-to-server automation	Service account
User-driven CLI or tool login	Magic code or CLI browser login
AI client with user consent	MCP OAuth

Choose the auth flow based on who is acting:

• a backend service should use a service account
• a human operator in a tool or CLI should use a user login flow
• an MCP client acting on behalf of a signed-in user should use OAuth

Service-account flow

Service accounts are created at the workspace level and exchange clientId plus clientSecret for bearer tokens.

curl -X POST "$COLABRA_API_URL/v1/auth/service-account/token" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "'"$CLIENT_ID"'",
    "clientSecret": "'"$CLIENT_SECRET"'"
  }'

The response returns:

• access_token
• refresh_token
• expires_in_seconds
• service-account metadata

Use the returned bearer token on /v1 requests.

This is the default for scheduled jobs, internal automations, and system-to-system integrations where no person is present at runtime.

Refresh and logout

Method	Path	Purpose
POST	/v1/auth/refresh	Rotate a refresh token into a new access-token pair
POST	/v1/auth/logout	Revoke the active bearer token and optional refresh token

/v1/auth/refresh requires both refreshToken and clientId.

User login flows

Magic-code login

Method	Path	Purpose
POST	/v1/auth/login/start	Start login by email, optionally with a CLI redirect URI
POST	/v1/auth/magic-code/start	Send a magic code directly
POST	/v1/auth/magic-code/verify	Exchange email and code for tokens

Use this flow for operator-facing tooling where a human can receive and enter a code.

CLI browser login

The CLI/browser flow is designed for tools that want to hand off login to the browser and then poll until completion.

Method	Path	Purpose
POST	/v1/auth/cli/start	Starts a browser-based CLI login flow
GET	/v1/auth/cli/browser-complete	Browser completion endpoint
GET	/v1/auth/cli/poll	Polls for pending, complete, or error state
GET	/v1/auth/cli/callback	SSO callback for CLI flows

Identity and workspace context

Method	Path	Purpose
GET	/v1/me	Return the authenticated principal and visible workspaces
GET	/v1/workspaces	List workspaces the principal can access

Service-account management

These endpoints require a user principal with workspace integration permissions.

Method	Path	Purpose
GET	/v1/service-accounts	List service accounts for a workspace
POST	/v1/service-accounts	Create a new service account
POST	/v1/service-accounts/{serviceAccountId}/rotate	Rotate credentials
POST	/v1/service-accounts/{serviceAccountId}/revoke	Revoke the service account

When a service account is created, Colabra also generates a webhook signing secret.

MCP OAuth

The MCP server uses OAuth endpoints rather than service-account bearer exchange.

Method	Path	Purpose
GET	/.well-known/oauth-authorization-server	OAuth server metadata
GET	/.well-known/oauth-protected-resource/mcp	Protected resource metadata
GET	/mcp/oauth/authorize	Authorization step
POST	/mcp/oauth/authorize/decision	Consent decision
POST	/mcp/oauth/register	Dynamic client registration
POST	/mcp/oauth/token	Token exchange

The MCP scope currently exposed is mcp:tools.

Use MCP OAuth only for MCP clients. It is not a general replacement for bearer-token auth on /v1.