Manage workspaces and users with the mabl API

With the mabl API, you can provision a workspace, keep its membership current, reclaim licenses that aren't being used, and build reporting dashboards for auditing purposes without clicking through the UI.

This article walks through the most common goals of manaing workspaces and users with the mabl API:

• Provision a workspace
• Onboard and offboard members
• Rename a workspace
• Reclaim unused licenses
• Monitor activity and seats
• Take inventory of your workspaces
• Retire a workspace

Before you start

The endpoints in this article are company-scoped: they act across every workspace your company owns, so they use a company-scoped API key rather than a workspace key. Account admins create company-scoped keys from the API keys tab of the account dashboard. See managing API keys for the full procedure.

Two company key types cover the goals in this article:

• Workspace lifecycle: provision, rename, and retire workspaces
• User management: onboard and offboard members, reclaim unused licenses, monitor activity and seats, and take inventory of your workspaces

You'll also need a few identifiers:

• Company and account IDs: company- and account-level endpoints require IDs, available from the API keys tab of the account dashboard: click the View IDs button.
• Workspace ID: workspace-level endpoints require a workspace ID, available from Settings > Workspace in the app.
• User ID: use the query users endpoint to look up the user IDs that the membership endpoints operate on.

Provision a workspace

For teams that keep a workspace per product, team, or client, creating the workspace can be a scripted step in your onboarding process instead of a manual one.

• Create a workspace: send a POST request to /companies/{company_id}/workspaces. Name the workspace, specify which account it belongs to, and assign its owners with owner_user_ids.

Owners must already be a member of one of your company's mabl workspaces, so a provisioning script that creates a workspace for a new team needs the owners' user IDs first. Use the query users endpoint to look them up, as described in onboard and offboard members below.

Set a credit allocation as you create

POST /companies/{company_id}/workspaces accepts credit_allocation and enforce_credit_limit, the same two settings available when you add a workspace from the account dashboard. A provisioning script can hand a new workspace its credit ceiling at creation time rather than leave it drawing on the account's shared pool until someone sets one.

Enforcement requires an allocation: set enforce_credit_limit without credit_allocation and there is no limit to enforce. For how allocations interact across the workspaces in an account, see how credit allocations work.

Onboard and offboard members

Connect these endpoints to your identity or HR tooling to keep workspace membership current as people join, change teams, or leave.

• Change a member's role: send a PATCH request to /workspaces/{workspace_id}/users/{id} with the new role: owner, editor, or viewer. This is useful when a teammate moves between roles—for example, promoting an editor to owner when they take over a workspace.
• Remove a member: send a DELETE request to /workspaces/{workspace_id}/users/{id}. Wire this into your offboarding process so access is revoked automatically when someone leaves.

Both endpoints support the If-Match header so concurrent updates don't overwrite each other, and both protect the last owner of a workspace from being demoted or removed so that automated offboarding can't accidentally leave a workspace without an owner.

Rename a workspace

• Rename a workspace: send a PATCH request to /workspaces/{workspace_id} with the new name. Useful for bringing workspace names back in line with your naming convention after a reorg, or for renaming several workspaces in one pass rather than opening each one in the app.

Reclaim unused licenses

To find licenses you can recover, start at the account level rather than checking each workspace by hand.

• List account users: call GET /accounts/{account_id}/users to list every user across the account's workspaces, deduplicated and with their account-scoped roles. Add the inactive filter to return only users with no recent activity. By default, "recent" means the last 90 days; set the optional lookback_days parameter to widen or narrow that window.
• Get account user: to confirm a candidate before acting, look up an individual user with GET /accounts/{account_id}/users/{id}, or review GET /accounts/{account_id}/users/{id}/activity for their last-active time, total actions, and a per-workspace breakdown.

Once you've confirmed a user no longer needs access, remove them from the account-level users dashboard or with the offboarding endpoint described above.

Monitor activity and seats

mabl classifies each user as an automator or a participant based on their test authoring activity. Use these endpoints to track that mix and align your seat allocation with actual usage.

• Account seat allocation and utilization: call GET /accounts/{account_id}/seats for a snapshot of allocated, used, and available seats, split into automators and participants.
• Per-user seat utilization for an account: for a closer look, call GET /accounts/{account_id}/seats/usage to get per-user seat utilization for a given month, with each user classified as an automator or participant. Feed this into a recurring report to watch your automator-to-participant ratio over time and right-size your account without manual audits.

Take inventory of your workspaces

• List workspaces in company: to build a company-wide view—for a governance dashboard, or to discover the workspace IDs that the other endpoints operate on—call GET /companies/{id}/workspaces. It returns every workspace in the company, grouped by the owning account.

Retire a workspace

• Delete a workspace: send a DELETE request to /workspaces/{workspace_id}.

Learn more

For full request and response details on every endpoint, see the mabl API reference.