Authentication and permissions

REST API v1 and MCP accept Bearer credentials. Use a workspace API key for server integrations or OAuth for a connected AI client. Public client forms use form/workspace slugs instead of credentials.

API keys

Create a REST API key in your workspace's integration settings, select the scopes needed, and save the secret when it is shown. Keys use wk_<workspace_hash>.<secret_key>. The workspace is derived from the key, and its owner is the acting user for writes.

curl 'https://my.bluesuite.app/api/v1/contacts' \
  -H "Authorization: Bearer $BLUESUITE_API_KEY"

Keep REST/general keys in your server or trusted client's secret store. Rotate by creating a replacement, updating the integration, and revoking the old key. Older keys without an associated owner must be recreated for v1.

Scopes

For the resource prefixes below, :read permits the listed reads and :write permits the listed writes. Each endpoint states the exact scope combination; a write scope does not automatically include read access.

Additional scopes include workspace:read, notifications:write, webhooks:read, webhooks:write, forms:read, forms:write, and custom_fields:read. Notice that scope spellings are not always identical to URL paths: service plans and installed equipment use underscores.

Comments use the parent's scope. Uploads need both a files scope and the parent's scope, except workspace line-item images, which need only the files scope. Lead creation needs contact, property, and request write scopes. Schedule/hold operations can require both job and event write access.

General read and write scopes act as wildcards for their respective actions. REST/fine-grained keys have no automatic resource access unless scopes are selected.

OAuth and workspace selection

For MCP, connect to https://my.bluesuite.app/api/mcp with a client supporting Streamable HTTP and OAuth discovery. Complete the authorization flow and choose the intended workspace. The OAuth client is mapped to that selected workspace; if the mapping is missing, reauthorize.

The protected-resource metadata is at:

https://my.bluesuite.app/.well-known/oauth-protected-resource/api/mcp

Use the authorization server advertised there rather than hardcoding one. See MCP setup for transport details. OAuth requests are subject to workspace membership, roles, feature permissions, and data visibility; an integration should not promise every user the same results.

REST v1 also accepts OAuth/session JWTs. A mapped OAuth token resolves the selected workspace. An internal session-token integration supplies x-workspace-id; membership is verified. API-key requests derive their workspace from the key and do not need this header.

Troubleshooting

Legacy webhook endpoints can still accept old key formats with an explicit workspace_id. This does not make old-format keys valid for REST v1 or MCP. Use a wk_ key for new server integrations.