Skip to main content
People belong to your organization in WorkOS; these routes manage them from the API, with no dashboard needed. They are for funders who call the API directly. A product that keeps its own user list and calls with an API key does not need them. Everything here is scoped to the caller’s own organization. members:manage (held by the owner and admin roles) is needed for /v1/members, settings:manage for the Admin Portal. An API key can hold members:manage too, but a caller can only give, change or remove a role whose permissions it holds itself.

​
Members

membership_id is the id in the list (om_...). The organization’s last owner can be neither demoted nor removed (409): make another owner first. A member managed by a directory (SCIM) is changed in the directory; WorkOS refuses the change with a 422 that says so. Every change is in the audit log (GET /v1/audit-log): member.invite, member.invitation_revoke, member.role_change, member.remove, member.session_revoke.

​
Single sign-on and directory sync

POST /v1/tenant/admin-portal with {"intent": "sso"} returns a link to the WorkOS Admin Portal for your organization, where your IT admin connects an identity provider (SAML or OIDC). Use dsync for directory sync (SCIM), domain_verification to prove a company email domain, or audit_logs for audit-log streaming. return_url (optional) is where the admin goes on leaving the portal.
The link expires five minutes after it is issued and lets whoever holds it change your sign-in setup. Send it only to your IT admin, and never log it.

​
Sessions

POST /v1/auth/logout with a person’s access token ends their session: its refresh token stops working. The response carries logout_url; open it in the browser to end AuthKit’s own session as well. An admin can end someone else’s with GET /v1/members/{user_id}/sessions (their active sessions in your organization) and POST /v1/members/{user_id}/sessions/{session_id}/revoke.
An access token is a signed token that is checked without asking WorkOS, so revoking a session cannot recall one already issued: it works until it expires, in minutes. Revoking stops it from being renewed. To cut someone off, remove them and revoke their sessions; their next token is refused.
Removing a member or changing a role takes effect the same way: the next access token carries the change.