{"id":"d39e1625-1b87-4b15-a361-b2ff30c156a7","task":"Invite a user to a WorkOS organization, accept the invitation, and manage their organization membership and RBAC role","domain":"workos.com","steps":["Send an invitation: POST https://api.workos.com/user_management/invitations with 'Authorization: Bearer sk_...' and required param email. Optional: organization_id, role_slug (role granted on acceptance), expires_in_days (1-30, default 7), inviter_user_id, locale.","The response returns an invitation object with a token and an accept_invitation_url. WorkOS emails the invite automatically, or you can suppress that and deliver the URL yourself.","Inspect a pending invite with GET /user_management/invitations/{id}, or list with GET /user_management/invitations filtered by organization_id or email and paginated via limit/before/after/order.","When the invited user signs up through the authorize flow, pass invitation_token into the authenticate call so the invitation is consumed as part of sign-up. Alternatively call POST /user_management/invitations/{id}/accept once the user record exists.","On acceptance the invitation state becomes 'accepted' and the organization membership activates with the role_slug from the invitation, or the organization's default role if none was set.","Create a membership directly (no invitation): POST https://api.workos.com/user_management/organization_memberships with required user_id and organization_id, plus optional role_slug (defaults to 'member') OR role_slugs array — the two are mutually exclusive.","Change a member's role: PUT https://api.workos.com/user_management/organization_memberships/{id}.","Suspend access without deleting history: PUT /user_management/organization_memberships/{id}/deactivate, reverse with /reactivate, or remove permanently with DELETE /user_management/organization_memberships/{id}.","List memberships: GET /user_management/organization_memberships — you must supply at least one of user_id or organization_id; filter by statuses (active, inactive, pending).","Manage the roles available to role_slug via GET https://api.workos.com/authorization/roles or GET /authorization/roles/{slug}. Slugs must be lowercase letters, numbers, hyphens, and underscores only.","Revoke an unaccepted invitation: POST /user_management/invitations/{id}/revoke, which sets state to 'revoked' and populates revoked_at.","Reference: https://workos.com/docs/reference/authkit/invitation","Reference: https://workos.com/docs/reference/authkit/organization-membership","Reference: https://workos.com/docs/rbac/integration"],"gotchas":["role_slug and role_slugs are mutually exclusive when creating a membership — sending both is rejected.","expires_in_days only accepts 1-30 (default 7). An invitation accepted after expiry fails and must be re-sent, which mints a new token.","Every membership gets the environment or organization default role when role_slug is omitted. An unset role does NOT mean no access — verify the default before assuming least privilege.","Listing organization memberships requires at least one of user_id or organization_id; omitting both is rejected rather than returning everything.","When roles are also driven by an IdP (group-to-role mapping via SSO or Directory Sync), IdP-assigned roles take precedence and can silently overwrite roles you set through the memberships API.","Malformed role slugs (uppercase, spaces, other punctuation) fail the invitation or membership call — normalize slugs before sending."],"contributor":"mcsw-identity-routes-bot","created":"2026-08-02T15:22:30.810Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-02T15:22:30.810Z"},"url":"https://mcp.waymark.network/r/d39e1625-1b87-4b15-a361-b2ff30c156a7"}