> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/merge-workforce/api/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).

> Build once. Connect to every API, tool, and LLM. Ship products and agents to production without owning the integration stack.


## API Docs

- Workforce API > People [List Persons](https://docs.merge.dev/merge-workforce/api/people/list-persons.md)
- Workforce API > People [Get Person](https://docs.merge.dev/merge-workforce/api/people/get-person.md)
- Workforce API > People [Update Person](https://docs.merge.dev/merge-workforce/api/people/update-person.md)
- Workforce API > People [Deactivate Person](https://docs.merge.dev/merge-workforce/api/people/deactivate-person.md)
- Workforce API > People [Reactivate Person](https://docs.merge.dev/merge-workforce/api/people/reactivate-person.md)
- Workforce API > Invites [List Invites](https://docs.merge.dev/merge-workforce/api/invites/list-invites.md)
- Workforce API > Invites [Create](https://docs.merge.dev/merge-workforce/api/invites/create-invite.md)
- Workforce API > Invites [Revoke](https://docs.merge.dev/merge-workforce/api/invites/revoke-invite.md)
- Workforce API > Invites [Resend](https://docs.merge.dev/merge-workforce/api/invites/resend-invite.md)
- Workforce API > Groups [List Groups](https://docs.merge.dev/merge-workforce/api/groups/list-groups.md)
- Workforce API > Groups [Create Group](https://docs.merge.dev/merge-workforce/api/groups/create-group.md)
- Workforce API > Groups [Get Group](https://docs.merge.dev/merge-workforce/api/groups/get-group.md)
- Workforce API > Groups [Delete Group](https://docs.merge.dev/merge-workforce/api/groups/delete-group.md)
- Workforce API > Groups [Rename Group](https://docs.merge.dev/merge-workforce/api/groups/update-group.md)
- Workforce API > Groups [List Managers](https://docs.merge.dev/merge-workforce/api/groups/list-managers.md)
- Workforce API > Groups [Assign Manager](https://docs.merge.dev/merge-workforce/api/groups/assign-manager.md)
- Workforce API > Groups [Remove Manager](https://docs.merge.dev/merge-workforce/api/groups/remove-manager.md)
- Workforce API > Groups [List Members](https://docs.merge.dev/merge-workforce/api/groups/list-members.md)
- Workforce API > Groups [Add Members](https://docs.merge.dev/merge-workforce/api/groups/add-members.md)
- Workforce API > Groups [Remove Member](https://docs.merge.dev/merge-workforce/api/groups/remove-member.md)
- Workforce API > Tool Access [List Blocks](https://docs.merge.dev/merge-workforce/api/tool-access/list-blocks.md)
- Workforce API > Tool Access [Add Block](https://docs.merge.dev/merge-workforce/api/tool-access/add-block.md)
- Workforce API > Tool Access [Remove Block](https://docs.merge.dev/merge-workforce/api/tool-access/remove-block.md)
- Workforce API > Tool Access [Get Group Policy](https://docs.merge.dev/merge-workforce/api/tool-access/get-group-policy.md)
- Workforce API > Tool Access [Set Group Policy](https://docs.merge.dev/merge-workforce/api/tool-access/set-group-policy.md)
- Workforce API > Tool Access [Delete Group Policy](https://docs.merge.dev/merge-workforce/api/tool-access/delete-group-policy.md)
- Workforce API > Tool Access [Get Organization Policy](https://docs.merge.dev/merge-workforce/api/tool-access/get-organization-policy.md)
- Workforce API > Tool Access [Set Organization Policy](https://docs.merge.dev/merge-workforce/api/tool-access/set-organization-policy.md)
- Workforce API > Tool Access [List Access Requests](https://docs.merge.dev/merge-workforce/api/tool-access/list-access-requests.md)
- Workforce API > Tool Access [Get Access Request](https://docs.merge.dev/merge-workforce/api/tool-access/get-access-request.md)
- Workforce API > Tool Access [Approve Access Request](https://docs.merge.dev/merge-workforce/api/tool-access/approve-access-request.md)
- Workforce API > Tool Access [Deny Access Request](https://docs.merge.dev/merge-workforce/api/tool-access/deny-access-request.md)
- Workforce API > Tool Access [Revoke Access Request](https://docs.merge.dev/merge-workforce/api/tool-access/revoke-access-request.md)
- Workforce API > Tool Access [Get User Policy](https://docs.merge.dev/merge-workforce/api/tool-access/get-user-policy.md)
- Workforce API > Tool Access [Set User Policy](https://docs.merge.dev/merge-workforce/api/tool-access/set-user-policy.md)
- Workforce API > Tool Access [Delete User Policy](https://docs.merge.dev/merge-workforce/api/tool-access/delete-user-policy.md)
- Workforce API > Tool Access [Get Effective Access](https://docs.merge.dev/merge-workforce/api/tool-access/get-effective-access.md)
- Workforce API > Skills [List Skills](https://docs.merge.dev/merge-workforce/api/skills/list-skills.md)
- Workforce API > Skills [Create Skill](https://docs.merge.dev/merge-workforce/api/skills/create-skill.md)
- Workforce API > Skills [Publishable Groups](https://docs.merge.dev/merge-workforce/api/skills/publishable-groups.md)
- Workforce API > Skills [Get Skill](https://docs.merge.dev/merge-workforce/api/skills/get-skill.md)
- Workforce API > Skills [Delete Skill](https://docs.merge.dev/merge-workforce/api/skills/delete-skill.md)
- Workforce API > Skills [Update Skill](https://docs.merge.dev/merge-workforce/api/skills/update-skill.md)
- Workforce API > Skills [Set Enablement](https://docs.merge.dev/merge-workforce/api/skills/set-enablement.md)
- Workforce API > Skills [Grant To Person](https://docs.merge.dev/merge-workforce/api/skills/grant-to-person.md)
- Workforce API > Skills [Revoke From Person](https://docs.merge.dev/merge-workforce/api/skills/revoke-from-person.md)
- Workforce API > Skills [Review Skill](https://docs.merge.dev/merge-workforce/api/skills/review-skill.md)
- Workforce API > Skills [Add Version](https://docs.merge.dev/merge-workforce/api/skills/add-version.md)
- Workforce API > Skills [Get Version](https://docs.merge.dev/merge-workforce/api/skills/get-version.md)
- Workforce API > Skills [Delete Version](https://docs.merge.dev/merge-workforce/api/skills/delete-version.md)
- Workforce API > Skills [Promote Version](https://docs.merge.dev/merge-workforce/api/skills/promote-version.md)
- Workforce API > Audit Log [List Audit Log Events](https://docs.merge.dev/merge-workforce/api/audit-log/list-audit-log-events.md)
- Workforce API > Scim [List Groups](https://docs.merge.dev/merge-workforce/api/scim/list-groups.md)
- Workforce API > Scim [Create Group](https://docs.merge.dev/merge-workforce/api/scim/create-group.md)
- Workforce API > Scim [Get Group](https://docs.merge.dev/merge-workforce/api/scim/get-group.md)
- Workforce API > Scim [Replace Group](https://docs.merge.dev/merge-workforce/api/scim/replace-group.md)
- Workforce API > Scim [Delete Group](https://docs.merge.dev/merge-workforce/api/scim/delete-group.md)
- Workforce API > Scim [Patch Group](https://docs.merge.dev/merge-workforce/api/scim/patch-group.md)
- Workforce API > Scim [List Resource Types](https://docs.merge.dev/merge-workforce/api/scim/list-resource-types.md)
- Workforce API > Scim [List Schemas](https://docs.merge.dev/merge-workforce/api/scim/list-schemas.md)
- Workforce API > Scim [Get Service Provider Config](https://docs.merge.dev/merge-workforce/api/scim/get-service-provider-config.md)
- Workforce API > Scim [List Users](https://docs.merge.dev/merge-workforce/api/scim/list-users.md)
- Workforce API > Scim [Create User](https://docs.merge.dev/merge-workforce/api/scim/create-user.md)
- Workforce API > Scim [Get User](https://docs.merge.dev/merge-workforce/api/scim/get-user.md)
- Workforce API > Scim [Replace User](https://docs.merge.dev/merge-workforce/api/scim/replace-user.md)
- Workforce API > Scim [Delete User](https://docs.merge.dev/merge-workforce/api/scim/delete-user.md)
- Workforce API > Scim [Patch User](https://docs.merge.dev/merge-workforce/api/scim/patch-user.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.merge.dev/openapi.json)
- [OpenAPI YAML](https://docs.merge.dev/openapi.yaml)