> This page is for Workforce.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Workforce API

> Reference for the Workforce API: base URL, organization API keys and their permission scopes, pagination, errors, and SCIM provisioning.

The Workforce API does what an Admin does in the console: manage people, Groups and members, tool access and access requests, skills, and the audit log.

## Base URL and authentication

```text
https://wf-api.merge.dev
```

Use an organization API key from **Settings → API keys**. It starts with `mfw_org_key_` and is shown once.

```http
Authorization: Bearer mfw_org_key_...
```

## Permission scopes

Each endpoint needs one permission. A call without it returns `403` with code `insufficient_scope`. Keys can't hold **Manage roles**, so assigning Group Managers stays in the console.

| Area          | Endpoints                           | Writes need            | Reads need         |
| ------------- | ----------------------------------- | ---------------------- | ------------------ |
| People        | `/api/v1/persons`                   | `manage_users`         | `view_users`       |
| Invites       | `/api/v1/invites`                   | `manage_users`         | `view_users`       |
| Groups        | `/api/v1/groups`                    | `manage_groups`        | `view_groups`      |
| Group members | `/api/v1/groups/{group_id}/members` | `manage_group_members` | `view_groups`      |
| Tool access   | `/api/v1/tool-access`               | `manage_tool_access`   | `view_tool_access` |
| Skills        | `/api/v1/skills`                    | `manage_skills`        | `view_skills`      |
| Audit log     | `/api/v1/audit-log-events`          |                        | `view_audit_trail` |

SCIM endpoints under `/scim/v2` take a SCIM token instead. See [SCIM](/merge-workforce/provisioning/scim).

## Pagination

Lists return `results` and `next_cursor`. Pass `next_cursor` as `cursor` until it is `null`. `limit` defaults to 50, max 100.

```json
{"results": [{"id": "6f1c2b9e-4a7d-4e3b-9c1a-2d5e8f0a7b34", "name": "Finance"}], "next_cursor": "WyIyMDI2LTEwLTI4VDE0OjAyOjExKzAwOjAwIiwgIjZmMWMyYjllIl0="}
```

## Errors

Errors have an `error` object with `code` and `message`, repeated as `detail`.

```json
{"error": {"code": "insufficient_scope", "message": "This API key's scopes do not allow this request."}, "detail": "This API key's scopes do not allow this request."}
```

| Status | Code                 | Cause                                                          |
| ------ | -------------------- | -------------------------------------------------------------- |
| `401`  | `unauthenticated`    | Missing, expired, or revoked key                               |
| `403`  | `insufficient_scope` | Key lacks the endpoint's permission                            |
| `422`  |                      | Body failed validation, with a top-level key per invalid field |

Next: [API keys](/merge-workforce/settings/api-keys).