Skip to main content
ClickFlow supports two authentication methods: API keys and OAuth. API keys work with both MCP and REST API. They’re the simplest way to authenticate and the only option for the REST API. Format: Keys start with cf_ak_ followed by a random string. Create a key: Dashboard > Settings > API Keys > Create API Key.

​
Headers

Every request requires an Authorization header: 
Authorization: Bearer cf_ak_your_key_here
Optionally, override the default organization: 
X-Organization-Id: org_abc123

​
Scopes

API keys are restricted by scopes. Each scope grants access to a specific tool.
ScopeAccess
tools:platform.list_roadmap_itemsSingle tool
tools:agents.*All agent tools
tools:platform.*All platform tools
tools:*All tools (full access)
When a key lacks a required scope, the request returns:
  • MCP: Error in tool response
  • API: 403 Forbidden
Human users authenticated via OAuth bypass scope checks entirely.

​
Key properties

PropertyDescription
statusactive, revoked, or expired
scopesArray of scope strings
expiresAtOptional expiration timestamp
lastUsedAtUpdated on each use
organizationIdDefault org for this key

​
OAuth (MCP only, for interactive sessions)

When connecting ClickFlow MCP to AI assistants like Claude or Cursor, OAuth lets the human user authenticate interactively without managing API keys. OAuth is not supported for the REST API. Flow:
  1. MCP client discovers auth requirements via /.well-known/oauth-protected-resource
  2. Client redirects to Clerk (ClickFlow’s auth provider) for login
  3. User authenticates and grants access
  4. MCP client receives a JWT token
  5. All subsequent tool calls use this token automatically
No setup required — MCP clients that support OAuth handle this automatically.

​
OAuth metadata endpoint

GET https://api.clickflow.com/v1/.well-known/oauth-protected-resource

{
  "resource": "https://api.clickflow.com/v1/mcp",
  "authorization_servers": ["https://your-app.clerk.accounts.dev"]
}

​
Error responses

​
401 Unauthorized

Returned when the token is missing, invalid, or expired. 
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.clickflow.com/v1/.well-known/oauth-protected-resource"

{"error": "unauthorized"}

​
403 Forbidden (API only)

Returned when an API key lacks the required scope. 
HTTP/1.1 403 Forbidden

{"detail": "Insufficient scope: tools:platform.create_roadmap_item"}