Authentication & security

Ordinary keys are created in Settings → Developers → API Keys. MCP connections use browser sign-in and consent, not a pasted API key. Do not use an application session token for external Query, Search or Events requests.

Send the full key over HTTPS in the Authorization header. Keys have the format wk_<live-or-test><key-id><secret>. The prefix shown in the key list is not a usable credential.

OData also accepts Basic authentication: use a label such as Workroomly for the username and the full Data Access key for the password. This supports analytics clients with a username/password connection dialog. Never use your Workroomly account password for this connection.

Do not put a key in the URL or query string. These examples are for server-side clients, not public browser code.

For Query, Search, Events and OData, the authenticated key determines the workroom. Changing a URL, filter or workroom header does not change that boundary. Create a different key in the intended workroom when switching tenants.

Data Access keys require explicit module permissions. CRM, Board and Desk also require at least one authorized subspace. REST Query/Search requests select a particular subspace with scope.crm_space_key, scope.board_key or scope.desk_key. OData reads across the subspaces already granted to that key; it does not take an extra workroom selector.

The supported module permissions are crm.*, pages.*, board.*, files.*, goals.*, desk.*, people.*, finance.*, procure.* and assets.*. The resource catalog describes the data available in each module.

Always select Integration permissions explicitly. An Integration key with an empty permission list permits all supported events and read resources in its workroom. It does not provide the explicit subspace allowlists of a Data Access key. Prefer Data Access for read-only jobs.

API keys carry integration authority associated with their workroom. They are not delegated user sessions. MCP is different: each call intersects the OAuth grant with the user’s current membership and native action permissions.

Only owners and admins can create, edit, rotate and revoke keys. Moderators can inspect developer settings. The workroom must have Developer tools enabled.

The server stores a hash of the key’s secret. The raw key is returned at creation or rotation; the management list returns only a masked prefix. Save it immediately in a secret manager. Existing ordinary keys have no configured expiry field, so set your own review and rotation schedule.

Rotate creates a new credential with the same purpose, mode, permissions and scopes, then immediately revokes the old credential. There is no overlap window. For a scheduled migration, create a separate replacement key, move consumers, verify a successful request, then revoke the old key. After a suspected leak, revoke immediately and investigate usage.

Purpose and mode are immutable after creation. To switch from Integration to Data Access, create a new key. Revoked keys cannot be reactivated. MCP delegation keys are managed through Connected assistants; reconnect an assistant instead of rotating its underlying delegation manually.

Test is a credential mode, not an isolated sandbox or a dry run. Test keys can act on records in their workroom. Test writes in a separate workroom with synthetic data.

The key list shows creation and last-use information. Last-use updates are coalesced over five minutes, so they are not a request-by-request activity stream. The backend records external-request audits, request IDs, response sizes and outcomes. Event Activity is the place to inspect incoming event processing. Successful external responses consume the workroom’s shared Data Transfer allowance.

MCP uses OAuth authorization code flow with PKCE S256 and a resource-specific audience. A compatible client opens the Workroomly sign-in and consent flow. You select a workroom and the offered CRM spaces, boards, Files folders or Meet rooms; read and write scopes are separate for each product.

Single-use authorization codes last five minutes, access tokens last up to ten minutes, and grants/refresh tokens last 30 days. Refresh rotates the token; detected refresh-token reuse revokes the grant. Disconnecting a connection or revoking its delegation removes access on subsequent requests.

Discovery only shows tools the token is permitted to use. Execution still checks live membership, grant, selected context, entitlement and native permissions. Tool visibility alone is not permission to perform an arbitrary action. See the MCP guide before connecting.