Workforce API

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

https://wf-api.merge.dev

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

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.

Pagination

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

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

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