API keys | Merge

An organization API key authenticates your automation against the Workforce API. It acts for the organization, limited to the permissions you give it.

Authorization: Bearer mfw_org_key_...

Organization API keys don’t work on the MCP endpoint, https://wf-api.merge.dev/mcp. Employees sign in there with OAuth, or with a personal access token (mfw_person_...) for clients that can’t complete OAuth.

Create a key

Only an Admin can create or revoke keys, under Settings → API keys. Set:

A name that says where it runs, such as okta-onboarding
Only the permissions it needs
An optional expiry of 1 to 365 days. Without one, it works until revoked

The value is shown once. An organization holds at most 50 live keys.

Permissions

A key can hold any permission except Manage roles. A call without the needed permission returns 403 with code insufficient_scope. Permissions are fixed at creation; to change them, create a replacement and revoke the old key.

Permission	What the key can do
`view_users`	List and read people and open invites
`manage_users`	Update, deactivate, and reactivate people, and send, resend, and revoke invites
`view_groups`	List and read Groups, their members, and their Managers
`manage_groups`	Create, rename, and delete Groups
`manage_group_members`	Add people to Groups and remove them
`view_tool_access`	Read tool access policies, blocks, and access requests
`manage_tool_access`	Change tool access policies and blocks, and approve, deny, or revoke access requests
`view_skills`	List and read skills and their versions
`manage_skills`	Create, update, publish, review, and delete skills
`view_audit_trail`	Read the audit log

Rotate a key

Keys can’t be regenerated in place.

Create a new key with the same permissions.
Deploy it everywhere the old one is used.
Wait until the old key’s last-used time stops moving.
Revoke the old key.

If a key leaks publicly, revoke it first.

Store keys safely

Keep keys out of source control and client-side code, and give each service its own key. The Audit trail records key creation, revocation, and every change a key makes.