Manage users and seats with the mabl API

With the mabl API, you can manage workspace membership, review user activity, and track seat usage across your account programmatically. Use these endpoints to keep membership in sync with your identity provider, reclaim licenses that aren't being used, and build governance dashboards without running manual audits.

This article walks through the most common goals:

• Onboard and offboard members
• Reclaim unused licenses
• Monitor activity and seats
• List company workspaces

Before you start

User and workspace management endpoints require a company-scoped User management API key. Account admins can create one from the API keys tab of the account dashboard. See managing API keys for the full procedure.

You'll also need a few identifiers:

• Account ID: account-level endpoints require an account ID, available from the account dropdown on the account dashboard.
• 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.

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.

Reclaim unused licenses

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

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.

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 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.

Call GET /accounts/{account_id}/seats for a snapshot of allocated, used, and available seats, split into automators and participants.

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.

List company workspaces

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

Learn more

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