WorkOS API
WorkOS REST API
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
WorkOS REST API
Endpoints 273
admin-portal
- POSTGenerate a Portal Link
/portal/generate_linkGenerate a Portal Link scoped to an Organization. - POSTRevoke a Portal Link
/portal/revoke_linkRevokes every Portal Link generated for the given organization with the given external_user_id, and immediately ends any Admin Portal sessions that were…
agents.blueprints
- GETList agent blueprints
/agents/blueprintsLists the agent blueprints in the current environment. - POSTCreate an agent blueprint
/agents/blueprintsCreates an agent blueprint: the template describing what an agent may do (its permission ceiling), who may invoke it, and the lifetimes of its sessions. - GETGet an agent blueprint
/agents/blueprints/:agent_blueprint_idRetrieves an agent blueprint by ID. - DELETEDelete an agent blueprint
/agents/blueprints/:agent_blueprint_idDeletes an agent blueprint along with its configuration, instances, and sessions. - PATCHUpdate an agent blueprint
/agents/blueprints/:agent_blueprint_idUpdates an agent blueprint. Omitted fields are left unchanged; provided lists replace the existing configuration.
agents.blueprints.tokens
- POSTMint an agent token
/agents/blueprints/:agent_blueprint_id/tokensMint an agent access token (and backing session) from an agent blueprint. The session can be user-delegated (exchanging a user access token), autonomous (the… - POSTValidate an agent token
/agents/blueprints/:agent_blueprint_id/tokens/validateValidates an agent access token: verifies its signature against the environment, that it was minted under this blueprint, and that the backing session is live…
agents.instances
- GETList agent instances
/agents/instancesLists the agent instances in the current environment. Instances are created implicitly when tokens are minted. - GETGet an agent instance
/agents/instances/:agent_instance_idRetrieves an agent instance by ID. - DELETEDelete an agent instance
/agents/instances/:agent_instance_idDeletes an agent instance along with its sessions, invalidating their refresh tokens.
agents.registrations
- PATCHLink a claim attempt to an external user
/agents/claims/attemptsLink an external user to a claim attempt and retrieve the code needed for the agent to complete the claim. The user is looked up by external ID; if no user… - POSTValidate an agent credential
/agents/credentials/validateValidate an agent credential — an API key or access token — against the environment of the API key used to authenticate the request. This is a read-only… - GETGet an agent registration
/agents/registrations/:idRetrieve the details of an agent registration by ID. The registration is scoped to the environment of the API key used to authenticate the request. - POSTRevoke an agent registration
/agents/registrations/:id/revokeRevoke an agent registration by ID. Revocation is permanent: the registration, its identity assertions, and every access token or API key issued from it stop…
agents.sessions
- GETList agent instance sessions
/agents/sessionsLists the agent instance sessions in the current environment. Sessions are created when tokens are minted. - GETGet an agent instance session
/agents/sessions/:agent_instance_session_idRetrieves an agent instance session by ID. - POSTRevoke an agent instance session
/agents/sessions/:agent_instance_session_id/revokeRevokes an agent instance session, invalidating its refresh token and every access token minted under it. Revocation is idempotent: revoking an…
api_keys
- POSTValidate API key
/api_keys/validationsValidate an API key value and return the API key object if valid. - DELETEDelete an API key
/api_keys/:idPermanently deletes an API key. This action cannot be undone. Once deleted, any requests using this API key will fail authentication. - POSTExpire an API key
/api_keys/:id/expireExpire an API key immediately, schedule a future expiration, or clear a scheduled future expiration. - GETList API keys for a user
/user_management/users/:userId/api_keysGet a list of API keys owned by a specific user. - POSTCreate an API key for a user
/user_management/users/:userId/api_keysCreate a new API key owned by a user. The user must have an active membership in the specified organization.
application.client-secrets
- GETList Client Secrets for a Connect Application
/connect/applications/:id/client_secretsList all client secrets associated with a Connect Application. - POSTCreate a new client secret for a Connect Application
/connect/applications/:id/client_secretsCreate new secrets for a Connect Application. - DELETEDelete a Client Secret
/connect/client_secrets/:idDelete (revoke) an existing client secret.
applications
- GETList Connect Applications
/connect/applicationsList all Connect Applications in the current environment with optional filtering. - POSTCreate a Connect Application
/connect/applicationsCreate a new Connect Application. Supports both OAuth and Machine-to-Machine (M2M) application types. - GETGet a Connect Application
/connect/applications/:idRetrieve details for a specific Connect Application by ID or client ID. - PUTUpdate a Connect Application
/connect/applications/:idUpdate an existing Connect Application. For OAuth applications, you can update redirect URIs. For all applications, you can update the name, description, and… - DELETEDelete a Connect Application
/connect/applications/:idDelete an existing Connect Application.
audit-logs
- GETList Actions
/audit_logs/actionsGet a list of all Audit Log actions in the current environment. - GETList Schemas
/audit_logs/actions/:actionName/schemasGet a list of all schemas for the Audit Logs action identified by :name. - POSTCreate Schema
/audit_logs/actions/:actionName/schemasCreates an Audit Log schema used to validate incoming Audit Log events, or returns the latest version if the submitted schema matches it. If the schema… - POSTCreate Event
/audit_logs/eventsCreate an Audit Log Event. This API supports idempotency which guarantees that performing the same operation multiple times will have the same result as if… - POSTCreate Export
/audit_logs/exportsCreate an Audit Log Export. Exports are scoped to a single organization within a specified date range. - GETGet Export
/audit_logs/exports/:auditLogExportIdGet an Audit Log Export. The URL will expire after 10 minutes. If the export is needed again at a later time, refetching the export will regenerate the URL. - GETGet Retention
/organizations/:id/audit_logs_retentionGet the configured event retention period for the given Organization. - PUTSet Retention
/organizations/:id/audit_logs_retentionSet the event retention period for the given Organization.
authorization
- GETList role assignments for a group
/authorization/groups/:group_id/role_assignmentsList all role assignments granted to a group. Each assignment represents a role granted to the group on a resource. - PUTReplace all role assignments for a group
/authorization/groups/:group_id/role_assignmentsReplace all role assignments for a group with the provided list. Existing assignments not in the list will be removed. - POSTAssign a role to a group
/authorization/groups/:group_id/role_assignmentsAssign a role to a group on a specific resource. - DELETERemove group role assignments by criteria
/authorization/groups/:group_id/role_assignmentsRemove role assignments from a group that match the provided criteria. Returns 404 when no matching active assignment is found. - PATCHUpdate role assignments for a group
/authorization/groups/:group_id/role_assignmentsAdd and remove role assignments for a group in a single atomic operation. Additions that already exist and removals that match no assignment are skipped. An… - GETGet a group role assignment
/authorization/groups/:group_id/role_assignments/:role_assignment_idGet a specific role assignment for a group by its ID. - DELETERemove a group role assignment
/authorization/groups/:group_id/role_assignments/:role_assignment_idRemove a specific role assignment from a group by its ID. - POSTCheck authorization
/authorization/organization_memberships/:organization_membership_id/checkCheck if an organization membership has a specific permission on a resource. Supports identification by resource_id OR by resource_external_id +… - GETList resources for organization membership
/authorization/organization_memberships/:organization_membership_id/resources?permission_slug=project:readReturns all child resources of a parent resource where the organization membership has a specific permission. This is useful for resource discovery—answering… - GETList effective permissions for an organization membership on a resource
/authorization/organization_memberships/:organization_membership_id/resources/:resource_id/permissionsReturns all permissions the organization membership effectively has on a resource, including permissions inherited through roles assigned to ancestor… - GETList effective permissions for an organization membership on a resource by external ID
/authorization/organization_memberships/:organization_membership_id/resources/:resource_type_slug/:external_id/permissionsReturns all permissions the organization membership effectively has on a resource identified by its external ID, including permissions inherited through roles… - GETList role assignments
/authorization/organization_memberships/:organization_membership_id/role_assignmentsList all role assignments for an organization membership. This returns all roles that have been assigned to the user on resources, including… - POSTAssign a role
/authorization/organization_memberships/:organization_membership_id/role_assignmentsAssign a role to an organization membership on a specific resource. - DELETERemove a role assignment
/authorization/organization_memberships/:organization_membership_id/role_assignmentsRemove a role assignment by role slug and resource. - DELETERemove a role assignment by ID
/authorization/organization_memberships/:organization_membership_id/role_assignments/:role_assignment_idRemove a role assignment using its ID. - GETList custom roles
/authorization/organizations/:organizationId/rolesGet a list of all roles that apply to an organization. This includes both environment roles and custom roles, returned in priority order. - POSTCreate a custom role
/authorization/organizations/:organizationId/rolesCreate a new custom role for this organization. - GETGet a custom role
/authorization/organizations/:organizationId/roles/:slugRetrieve a role that applies to an organization by its slug. This can return either an environment role or a custom role. - DELETEDelete a custom role
/authorization/organizations/:organizationId/roles/:slugDelete an existing custom role. - PATCHUpdate a custom role
/authorization/organizations/:organizationId/roles/:slugUpdate an existing custom role. Only the fields provided in the request body will be updated. - PUTSet permissions for a custom role
/authorization/organizations/:organizationId/roles/:slug/permissionsReplace all permissions on a custom role with the provided list. - POSTAdd a permission to a custom role
/authorization/organizations/:organizationId/roles/:slug/permissionsAdd a single permission to a custom role. If the permission is already assigned to the role, this operation has no effect. - DELETERemove a permission from a custom role
/authorization/organizations/:organizationId/roles/:slug/permissions/:permissionSlugRemove a single permission from a custom role by its slug. - GETGet a resource by external ID
/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_idRetrieve the details of an authorization resource by its external ID, organization, and resource type. This is useful when you only have the external ID from… - DELETEDelete an authorization resource by external ID
/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_idDelete an authorization resource by organization, resource type, and external ID. This also deletes all descendant resources. - PATCHUpdate a resource by external ID
/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_idUpdate an existing authorization resource using its external ID. - GETList memberships for a resource by external ID
/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id/organization_memberships?permission_slug=project:readReturns all organization memberships that have a specific permission on a resource, using the resource's external ID. This is useful for answering "Who can… - GETList role assignments for a resource by external ID
/authorization/organizations/:organization_id/resources/:resource_type_slug/:external_id/role_assignmentsList all role assignments granted on a resource, identified by its external ID. Each assignment includes the organization membership it was granted to. - GETList resources
/authorization/resourcesGet a paginated list of authorization resources. - POSTCreate an authorization resource
/authorization/resourcesCreate a new authorization resource. - GETGet a resource
/authorization/resources/:resource_idRetrieve the details of an authorization resource by its ID. - DELETEDelete an authorization resource
/authorization/resources/:resource_idDelete an authorization resource and all its descendants. - PATCHUpdate a resource
/authorization/resources/:resource_idUpdate an existing authorization resource. - GETList organization memberships for resource
/authorization/resources/:resource_id/organization_memberships?permission_slug=document:editReturns all organization memberships that have a specific permission on a resource instance. This is useful for answering "Who can access this resource?". - GETList role assignments for a resource
/authorization/resources/:resource_id/role_assignmentsList all role assignments granted on a specific resource instance. Each assignment includes the organization membership it was granted to. - GETList environment roles
/authorization/rolesList all environment roles in priority order. - POSTCreate an environment role
/authorization/rolesCreate a new environment role. - GETGet an environment role
/authorization/roles/:slugGet an environment role by its slug. - PATCHUpdate an environment role
/authorization/roles/:slugUpdate an existing environment role. - PUTSet permissions for an environment role
/authorization/roles/:slug/permissionsReplace all permissions on an environment role with the provided list. - POSTAdd a permission to an environment role
/authorization/roles/:slug/permissionsAdd a single permission to an environment role. If the permission is already assigned to the role, this operation has no effect.
client
- POSTGenerate a Widgets API token
/client/tokenGenerate a short-lived, session-bound token for the Widgets API, scoped to an organization and user.
connections
- GETList Connections
/connectionsGet a list of all of your existing connections matching the criteria specified. - POSTCreate a Connection
/connectionsCreates a new connection for an organization. Provide saml_options or oidc_options to configure the identity provider. When external_id matches an existing… - GETList IdP signing certificates
/connections/:connectionId/saml_idp_signing_certsLists every Identity Provider signing certificate on the connection, including expired ones, oldest first. - POSTCreate an IdP signing certificate
/connections/:connectionId/saml_idp_signing_certsAdds an Identity Provider signing certificate to the connection, so SAML responses signed with its key can be verified. Use this to import a new certificate… - DELETEDelete an IdP signing certificate
/connections/:connectionId/saml_idp_signing_certs/:certificateIdRemoves an Identity Provider signing certificate from the connection. The last remaining certificate cannot be deleted. A certificate still published in the… - GETList SP encryption certificates
/connections/:connectionId/saml_sp_encryption_certsLists the public certificates the Identity Provider can use to encrypt SAML responses sent to WorkOS, including expired ones, oldest first. - POSTCreate an SP encryption certificate
/connections/:connectionId/saml_sp_encryption_certsGenerates a new encryption key pair for the connection and returns its public certificate. WorkOS holds the private key, so the request takes no body — to… - DELETEDelete an SP encryption certificate
/connections/:connectionId/saml_sp_encryption_certs/:certificateIdRemoves an encryption key pair from the connection. SAML responses encrypted with its certificate can no longer be decrypted, so remove the certificate from… - GETGet the SP signing certificate
/connections/:connectionId/saml_sp_signing_certReturns the public certificate the Identity Provider can use to verify the signature of SAML requests sent by WorkOS. Responds with 404 when the connection… - POSTCreate an SP signing certificate
/connections/:connectionId/saml_sp_signing_certGenerates a new request signing key pair for the connection and returns its public certificate. WorkOS holds the private key, so the request takes no body —… - DELETEDelete the SP signing certificate
/connections/:connectionId/saml_sp_signing_cert/:certificateIdRemoves the request signing key pair from the connection, after which SAML requests are sent unsigned. Delete the certificate before creating its replacement… - GETGet a Connection
/connections/:idGet the details of an existing connection. - DELETEDelete a Connection
/connections/:idPermanently deletes an existing connection. It cannot be undone. - PATCHUpdate a Connection
/connections/:idUpdates an existing connection. Only the provided fields are changed; fields that accept null are reset to their default behavior.
directories
- GETList Directories
/directoriesGet a list of all of your existing directories matching the criteria specified. - GETGet a Directory
/directories/:idGet the details of an existing directory. - DELETEDelete a Directory
/directories/:idPermanently deletes an existing directory. It cannot be undone. - POSTSync a Directory
/directories/:id/syncRequest an asynchronous sync from the directory provider. Currently supports Google Workspace directories in linked or validating state. Manual requests share…
directory-groups
- GETList Groups for a Directory
/directories/:directoryId/groupsGet a list of the Directory Groups in a Directory, optionally filtered to the groups a Directory User belongs to. - GETGet a Group for a Directory
/directories/:directoryId/groups/:groupIdGet the details of a Directory Group in a Directory. - GETList Directory Groups
/directory_groupsDeprecated. Get a list of all of existing directory groups matching the criteria specified. Deprecated: use GET /directories/{directoryId}/groups instead. - GETGet a Directory Group
/directory_groups/:idDeprecated. Get the details of an existing Directory Group. Deprecated: use GET /directories/{directoryId}/groups/{groupId} instead.
directory-users
- GETList Users for a Directory
/directories/:directoryId/usersGet a list of the Directory Users in a Directory, optionally filtered to the members of a Directory Group. - GETGet a User for a Directory
/directories/:directoryId/users/:userIdGet the details of a Directory User in a Directory. - GETList Directory Users
/directory_usersDeprecated. Get a list of all of existing Directory Users matching the criteria specified. Deprecated: use GET /directories/{directoryId}/users instead. - GETGet a Directory User
/directory_users/:idDeprecated. Get the details of an existing Directory User. Deprecated: use GET /directories/{directoryId}/users/{userId} instead.
events
- GETList events
/events?events=dsync.user.created,dsync.user.updatedList events for the current environment. Events are returned oldest first; use after to page forward.
feature-flags
- GETList feature flags
/feature-flagsGet a list of all of your existing feature flags matching the criteria specified. - GETGet a feature flag
/feature-flags/:slugGet the details of an existing feature flag by its slug. - PUTDisable a feature flag
/feature-flags/:slug/disableDisables a feature flag in the current environment. - PUTEnable a feature flag
/feature-flags/:slug/enableEnables a feature flag in the current environment.
feature-flags.targets
- POSTAdd a feature flag target
/feature-flags/:slug/targets/:resourceIdEnables a feature flag for a specific target in the current environment. Currently, supported targets include users and organizations. - DELETERemove a feature flag target
/feature-flags/:slug/targets/:resourceIdRemoves a target from the feature flag's target list in the current environment. Currently, supported targets include users and organizations.
groups
- GETList groups
/organizations/:organizationId/groupsGet a paginated list of groups within an organization. - POSTCreate a group
/organizations/:organizationId/groupsCreate a new group within an organization. - GETGet a group
/organizations/:organizationId/groups/:groupIdRetrieve a group by its ID within an organization. - DELETEDelete a group
/organizations/:organizationId/groups/:groupIdDelete a group from an organization. - PATCHUpdate a group
/organizations/:organizationId/groups/:groupIdUpdate an existing group. Only the fields provided in the request body will be updated. - GETList Group members
/organizations/:organizationId/groups/:groupId/organization-membershipsGet a list of organization memberships in a group. - POSTAdd a member to a Group
/organizations/:organizationId/groups/:groupId/organization-membershipsAdd an organization membership to a group. - PATCHUpdate Group members
/organizations/:organizationId/groups/:groupId/organization-membershipsAdds and removes organization memberships for a group in a single atomic operation. Organization memberships not listed in add or remove are left unchanged.… - DELETERemove a member from a Group
/organizations/:organizationId/groups/:groupId/organization-memberships/:omIdRemove an organization membership from a group.
multi-factor-auth
- POSTEnroll Factor
/auth/factors/enrollEnrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge. - GETGet Factor
/auth/factors/:idGets an Authentication Factor. - DELETEDelete Factor
/auth/factors/:idPermanently deletes an Authentication Factor. It cannot be undone. - POSTChallenge Factor
/auth/factors/:id/challengeCreates a Challenge for an Authentication Factor.
multi-factor-auth.challenges
- POSTVerify Challenge
/auth/challenges/:id/verifyVerifies an Authentication Challenge.
organization-domains
- POSTCreate an Organization Domain
/organization_domainsCreates a new Organization Domain. - GETGet an Organization Domain
/organization_domains/:idGet the details of an existing organization domain. - DELETEDelete an Organization Domain
/organization_domains/:idPermanently deletes an organization domain. It cannot be undone. - POSTVerify an Organization Domain
/organization_domains/:id/verifyInitiates verification process for an Organization Domain.
organizations
- GETList Organizations
/organizationsGet a list of all of your existing organizations matching the criteria specified. - POSTCreate an Organization
/organizationsCreates a new organization in the current environment. - GETGet an Organization by External ID
/organizations/external_id/:external_idGet the details of an existing organization by an external identifier. - GETGet an Organization
/organizations/:idGet the details of an existing organization. - PUTUpdate an Organization
/organizations/:idUpdates an organization in the current environment. - DELETEDelete an Organization
/organizations/:idPermanently deletes an organization in the current environment. It cannot be undone. - GETGet Audit Log Configuration
/organizations/:id/audit_log_configurationGet the unified view of audit log trail and stream configuration for an organization.
organizations.api_keys
- GETList API keys for an organization
/organizations/:organizationId/api_keysGet a list of all API keys for an organization. - POSTCreate an API key for an organization
/organizations/:organizationId/api_keysCreate a new API key for an organization.
organizations.authorized-applications
- GETList authorized applications
/organizations/:organization_id/authorized_applicationsGet a list of all Connect applications that users in the organization have authorized.
organizations.data-providers
- GETGet an organization connected account
/organizations/:organization_id/connected_accounts/:slugRetrieves an organization's connected account for a specific provider. - PUTUpdate an organization connected account
/organizations/:organization_id/connected_accounts/:slugUpdates an organization's connected account tokens, scopes, state, or provider configuration for a specific provider. - POSTImport an organization connected account
/organizations/:organization_id/connected_accounts/:slugImports an organization-owned connected account by providing OAuth tokens directly. Omit connection_intent to create only the compatibility connection, or set… - DELETEDelete an organization connected account
/organizations/:organization_id/connected_accounts/:slugDisconnects the organization's account for the provider, including removing any stored access and refresh tokens. A member will need to reauthorize if the… - GETList providers for an organization
/organizations/:organization_id/data_providersRetrieves the organization-owned providers configured for your environment and the organization's connected account information for each. Providers owned by…
organizations.feature-flags
- GETList enabled feature flags for an organization
/organizations/:organizationId/feature-flagsGet a list of all enabled feature flags for an organization.
organizations.it-contacts
- GETList IT contacts
/organizations/:organization_id/it_contactsGet the IT contacts for an organization. - POSTCreate an IT contact
/organizations/:organization_id/it_contactsAdd an IT contact to an organization. No Admin Portal invitation is sent, though the contact is notified if the organization has a connection certificate… - DELETEDelete an IT contact
/organizations/:organization_id/it_contacts/:contact_idRemove an IT contact from an organization and revoke the contact's active setup links. - POSTInvite an IT contact
/organizations/:organization_id/it_contacts/:contact_id/inviteCreate an Admin Portal setup link and email it to the IT contact. An organization can have at most one active invitation. - POSTRevoke an IT contact's invitation
/organizations/:organization_id/it_contacts/:contact_id/revokeRevoke the organization's active Admin Portal invitation.
permissions
- GETList permissions
/authorization/permissionsGet a list of all permissions in your WorkOS environment. - POSTCreate a permission
/authorization/permissionsCreate a new permission in your WorkOS environment. The permission can then be assigned to environment roles and custom roles. - GETGet a permission
/authorization/permissions/:slugRetrieve a permission by its unique slug. - DELETEDelete a permission
/authorization/permissions/:slugDelete an existing permission. System permissions cannot be deleted. - PATCHUpdate a permission
/authorization/permissions/:slugUpdate an existing permission. Only the fields provided in the request body will be updated.
pipes
- GETList data integrations
/data-integrationsLists the environment's data integrations configured with custom or organization credentials, including custom providers and API key integrations. Both… - POSTCreate a data integration
/data-integrationsCreates a data integration for a provider. Set credentials.type to custom to use your own OAuth app credentials or organization to have each organization… - POSTFinish connection
/data-integrations/finishSaves a connection that was started with code_challenge. After the user authorizes, WorkOS redirects them to return_to with a connect_code and state. Call… - GETGet a data integration
/data-integrations/:slugRetrieves the user-owned data integration by its slug. - PUTUpdate a data integration
/data-integrations/:slugUpdates the description, enabled state, or custom credentials of the user-owned data integration. For custom providers, custom_provider updates the OAuth… - DELETEDelete a data integration
/data-integrations/:slugDeletes the user-owned data integration and all of its connected installations. For a custom provider, the provider definition is deleted once no… - PUTUpsert an API key for a connected account
/data-integrations/:slug/api-keyCreates or updates an API-key-based installation for the specified integration, owned by the user or, when connection_owner is organization, shared by the… - POSTCreate another API key connected account
/data-integrations/:slug/api-keyCreates another API key-based connected account for the specified integration, owned by the user or, when connection_owner is organization, shared by the… - POSTGet authorization URL
/data-integrations/:slug/authorizeGenerates an OAuth authorization URL to initiate the connection flow for a user. Redirect the user to the returned URL to begin the OAuth flow with the… - PUTUpsert client credentials for a connected account
/data-integrations/:slug/client-credentialsCreates or updates a client-credentials-based installation for the specified integration, owned by the user or, when connection_owner is organization, shared… - POSTCreate another client credentials connected account
/data-integrations/:slug/client-credentialsCreates another client credentials-based connected account for the specified integration, owned by the user or, when connection_owner is organization, shared… - POSTVend credentials for a connected account
/data-integrations/:slug/credentialsReturns credentials for a user's connected account. Branches on the installation's auth_method: OAuth installations return an access token (refreshed if… - GETGet an organization-owned data integration
/data-integrations/:slug/organizationRetrieves the organization-owned data integration for a provider by its slug. The /organization suffix selects the environment-level organization-owned root… - PUTUpdate an organization-owned data integration
/data-integrations/:slug/organizationUpdates the description, enabled state, or custom credentials of the organization-owned data integration for a provider. For custom providers, custom_provider… - DELETEDelete an organization-owned data integration
/data-integrations/:slug/organizationDeletes the organization-owned data integration for a provider and all of its connected installations. For a custom provider, the provider definition is… - POSTGet an access token for a connected account
/data-integrations/:slug/tokenFetches a valid OAuth access token for a user's connected account. WorkOS automatically handles token refresh, ensuring you always receive a valid,…
pipes.provider
- GETList providers for an organization
/organizations/:organizationId/data_integration_configurationsReturns a list of all providers available to the specified organization, along with any configured custom OAuth scopes, enabled state, and… - PUTConfigure a provider for an organization
/organizations/:organizationId/data_integration_configurations/:slugCreates or updates an organization's provider configuration. Use this endpoint to enable or disable a provider, set custom OAuth scopes, or supply…
platform.teams
- POSTCreate a team
/platform/teamsCreates a team along with its default project, a staging environment, and a production environment. An admin invitation is sent to admin_email, onboarding is… - GETGet a team
/platform/teams/:team_idReturns a team, and doubles as a health check on the platform's access to it. Read production_state before attempting to create a production environment.
radar
- POSTCreate an attempt
/radar/attemptsAssess a request for risk using the Radar engine and receive a verdict. - PUTUpdate a Radar attempt
/radar/attempts/:idYou may optionally inform Radar that an authentication attempt or challenge was successful using this endpoint. Some Radar controls depend on tracking recent… - POSTAdd an entry to a Radar list
/radar/lists/:type/:actionAdd an entry to a Radar list. - DELETERemove an entry from a Radar list
/radar/lists/:type/:actionRemove an entry from a Radar list.
sso
- GETInitiate SSO
/sso/authorize?client_id=client_01HZBC6N1EB1ZY7KG32X&redirect_uri=https://example.com/callback&response_type=codeInitiates the single sign-on flow. - GETLogout Redirect
https://auth.workos.com/sso/logout?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4Logout allows to sign out a user from your application by triggering the identity provider sign out flow. This GET endpoint should be a redirection, since the… - POSTLogout Authorize
https://auth.workos.com/sso/logout/authorizeYou should call this endpoint from your server to generate a logout token which is required for the Logout Redirect endpoint. - GETGet a User Profile
/sso/profileExchange an access token for a user's Profile. Because this profile is returned in the Get a Profile and Token endpoint your application usually does not need… - POSTGet a Profile and Token
/sso/token?client_id=client_01HZBC6N1EB1ZY7KG32X&client_secret=sk_example_123456789&grant_type=authorization_codeGet an access token along with the user Profile using the code passed to your Redirect URI.
user-management.authentication
- POSTAuthenticate
/user_management/authenticateAuthenticate a user with a specified authentication method. - GETGet an authorization URL
/user_management/authorize?response_type=code&redirect_uri=https://example.com/callback&client_id=client_01HZBC6N1EB1ZY7KG32XGenerates an OAuth 2.0 authorization URL to authenticate a user with AuthKit or SSO. - POSTGet device authorization URL
/user_management/authorize/deviceInitiates the CLI Auth flow by requesting a device code and verification URLs. This endpoint implements the OAuth 2.0 Device Authorization Flow (RFC 8628) and… - POSTSend a Radar SMS challenge
/user_management/radar_challengesSends a one-time verification code over SMS to a user as part of a Radar challenge. Use the returned verification_id to authenticate the user with the… - GETGet Radar Challenge details
/user_management/radar_challenges/:idGet the details of an existing Radar Challenge, including the OTP code. - GETLogout
/user_management/sessions/logout?session_id=session_01H93ZY4F80QPBEZ1R5B2SHQG8Logout a user from the current session. - POSTRevoke Session
/user_management/sessions/revokeRevoke a user session.
user-management.authkit-oauth-resources
- GETList MCP resource indicators
/user_management/authkit_oauth_resourcesLists the MCP resource indicators configured for an environment. - POSTCreate an MCP resource indicator
/user_management/authkit_oauth_resourcesAdds an MCP resource indicator (RFC 8707) to an environment, leaving any others in place. - DELETEDelete an MCP resource indicator
/user_management/authkit_oauth_resources/:idRemoves an MCP resource indicator from an environment. Any application consents granted against it are removed too.
user-management.cors-origins
- GETList CORS origins
/user_management/cors_originsLists the CORS origins for the current environment. - POSTCreate a CORS origin
/user_management/cors_originsCreates a new CORS origin for the API key's application. CORS origins allow browser-based applications to make requests to the WorkOS API.
user-management.data-providers
- GETGet a connected account
/user_management/users/:user_id/connected_accounts/:slugRetrieves a user's connected account for a specific provider. - PUTUpdate a connected account
/user_management/users/:user_id/connected_accounts/:slugUpdates a user's connected account tokens, scopes, state, or provider configuration for a specific provider. - POSTImport a connected account
/user_management/users/:user_id/connected_accounts/:slugImports a connected account for a user by providing OAuth tokens directly. Use this to migrate existing connections or set up connections without going… - DELETEDelete a connected account
/user_management/users/:user_id/connected_accounts/:slugDisconnects WorkOS's account for the user, including removing any stored access and refresh tokens. The user will need to reauthorize if they want to… - GETList providers for a user
/user_management/users/:user_id/data_providersRetrieves a list of available providers and the user's connection status for each. Returns all providers configured for your environment, along with the…
user-management.invitations
- GETList invitations
/user_management/invitationsGet a list of all of invitations matching the criteria specified. - POSTSend an invitation
/user_management/invitationsSends an invitation email to the recipient. - GETFind an invitation by token
/user_management/invitations/by_token/:tokenRetrieve an existing invitation using the token. - GETGet an invitation
/user_management/invitations/:idGet the details of an existing invitation. - POSTAccept an invitation
/user_management/invitations/:id/acceptAccepts an invitation and, if linked to an organization, activates the user's membership in that organization. - POSTResend an invitation
/user_management/invitations/:id/resendResends an invitation email to the recipient. The invitation must be in a pending state. - POSTRevoke an invitation
/user_management/invitations/:id/revokeRevokes an existing invitation.
user-management.jwt-template
- GETGet JWT template
/user_management/jwt_templateGet the JWT template for the current environment. - PUTUpdate JWT template
/user_management/jwt_templateUpdate the JWT template for the current environment.
user-management.magic-auth
- POSTCreate a Magic Auth code
/user_management/magic_authCreates a one-time authentication code that can be sent to the user's email address. The code expires in 10 minutes. To verify the code, authenticate the user… - GETGet Magic Auth code details
/user_management/magic_auth/:idGet the details of an existing Magic Auth code that can be used to send an email to a user for authentication.
user-management.multi-factor-authentication
- GETList authentication factors
/user_management/users/:userlandUserId/auth_factorsLists the authentication factors for a user. - POSTEnroll an authentication factor
/user_management/users/:userlandUserId/auth_factorsEnrolls a user in a new authentication factor.
user-management.organization-membership
- GETList organization memberships
/user_management/organization_membershipsGet a list of all organization memberships matching the criteria specified. At least one of user_id or organization_id must be provided. By default only… - POSTCreate an organization membership
/user_management/organization_membershipsCreates a new active organization membership for the given organization and user. Calling this API with an organization and user that match an inactive… - GETGet an organization membership
/user_management/organization_memberships/:idGet the details of an existing organization membership. - PUTUpdate an organization membership
/user_management/organization_memberships/:idUpdate the details of an existing organization membership. - DELETEDelete an organization membership
/user_management/organization_memberships/:idPermanently deletes an existing organization membership. It cannot be undone. - PUTDeactivate an organization membership
/user_management/organization_memberships/:id/deactivateDeactivates an active organization membership. Emits an organization_membership.updated event upon successful deactivation. Deactivating an inactive… - PUTReactivate an organization membership
/user_management/organization_memberships/:id/reactivateReactivates an inactive organization membership, retaining the pre-existing role(s). Emits an organization_membership.updated event upon successful…
user-management.organization-membership.groups
- GETList groups
/user_management/organization_memberships/:omId/groupsGet a list of groups that an organization membership belongs to.
user-management.redirect-uris
- GETList redirect URIs
/user_management/redirect_urisLists the redirect URIs for an environment. - POSTCreate a redirect URI
/user_management/redirect_urisCreates a new redirect URI for an application. - DELETEDelete a redirect URI
/user_management/redirect_uris/:idDeletes a redirect URI from an application.
user-management.session-tokens
- GETGet JWKS
/sso/jwks/:clientIdReturns the JSON Web Key Set (JWKS) containing the public keys used for verifying access tokens.
user-management.users
- GETGet an email verification code
/user_management/email_verification/:idGet the details of an existing email verification code that can be used to send an email to a user for verification. - POSTCreate a password reset token
/user_management/password_resetCreates a one-time token that can be used to reset a user's password. - POSTReset the password
/user_management/password_reset/confirmSets a new password using the token query parameter from the link that the user received. Successfully resetting the password will verify a user's email, if… - GETGet a password reset token
/user_management/password_reset/:idGet the details of an existing password reset token that can be used to reset a user's password. - GETList users
/user_management/usersGet a list of all of your existing users matching the criteria specified. - POSTCreate a user
/user_management/usersCreate a new user in the current environment. - GETGet a user by external ID
/user_management/users/external_id/:external_idGet the details of an existing user by an external identifier. - GETGet a user
/user_management/users/:idGet the details of an existing user. - PUTUpdate a user
/user_management/users/:idUpdates properties of a user. The omitted properties will be left unchanged. - DELETEDelete a user
/user_management/users/:idPermanently deletes a user in the current environment. It cannot be undone. - POSTConfirm email change
/user_management/users/:id/email_change/confirmConfirms an email change using the one-time code received by the user. - POSTSend email change code
/user_management/users/:id/email_change/sendSends an email that contains a one-time code used to change a user's email address. - POSTVerify email
/user_management/users/:id/email_verification/confirmVerifies an email address using the one-time code received by the user. - POSTSend verification email
/user_management/users/:id/email_verification/sendSends an email that contains a one-time code used to verify a user's email address. - GETGet user identities
/user_management/users/:id/identitiesGet a list of identities associated with the user. A user can have multiple associated identities after going through identity linking. Currently only OAuth… - GETList sessions
/user_management/users/:id/sessionsGet a list of all active sessions for a specific user.
user-management.users.authorized-applications
- GETList authorized applications
/user_management/users/:user_id/authorized_applicationsGet a list of all Connect applications that the user has authorized. - DELETEDelete an authorized application
/user_management/users/:user_id/authorized_applications/:application_idDelete an existing Authorized Connect Application.
user-management.users.feature-flags
- GETList enabled feature flags for a user
/user_management/users/:userId/feature-flagsGet a list of all enabled feature flags for the provided user. This includes feature flags enabled specifically for the user as well as any organizations that…
user-management.waitlists
- DELETEDelete a waitlist entry
/user_management/waitlist_entries/:idRemove the entry from the waitlist. Its email address can join again unless a user with that email now exists in the environment. Deleting the entry does not… - POSTApprove a waitlist entry
/user_management/waitlist_entries/:id/approveApprove a waitlist entry, create an invitation for its email address, and send the invitation email. Approving a denied entry reverses the denial. The… - POSTDeny a waitlist entry
/user_management/waitlist_entries/:id/denyDeny a pending waitlist entry. Denying an entry that is not pending fails with the code invalid_state. A denial can be reversed by approving the entry. - GETList waitlists
/user_management/waitlistsGet a list of the waitlists in the environment. All waitlists are returned in a single response — this endpoint is not paginated, so the list_metadata cursors… - GETGet a waitlist
/user_management/waitlists/:idGet the details of an existing waitlist. - GETList waitlist entries
/user_management/waitlists/:id/entriesGet a list of entries on a waitlist matching the criteria specified. - POSTCreate a waitlist entry
/user_management/waitlists/:id/entriesAdd an email address to the waitlist. Email addresses are normalized and unique per environment: a request for an email address already on the waitlist…
vault
- POSTCreate a data key
/vault/v1/keys/data-keyGenerate an isolated encryption key for local encryption operations. - POSTDecrypt a data key
/vault/v1/keys/decryptDecrypt a previously encrypted data key from WorkOS Vault. - POSTRe-encrypt a data key
/vault/v1/keys/rekeyDecrypt an existing data key and re-encrypt it under a new key context. - GETList objects
/vault/v1/kvList all encrypted objects with cursor-based pagination. - POSTCreate an object
/vault/v1/kvEncrypt and store a new key-value object. - GETRead an object by name
/vault/v1/kv/name/:nameFetch and decrypt an object by its unique name. - GETRead an object by ID
/vault/v1/kv/:idFetch and decrypt an object by its unique identifier. - PUTUpdate an object
/vault/v1/kv/:idUpdate the value of an existing encrypted object. - DELETEDelete an object
/vault/v1/kv/:idDelete an encrypted object. - GETDescribe an object
/vault/v1/kv/:id/metadataFetch metadata for an object without decrypting it. - GETList object versions
/vault/v1/kv/:id/versionsRetrieve all versions for a specific object.
webhooks
- GETList Webhook Endpoints
/webhook_endpointsGet a list of all of your existing webhook endpoints. - POSTCreate a Webhook Endpoint
/webhook_endpointsCreate a new webhook endpoint to receive event notifications. - DELETEDelete a Webhook Endpoint
/webhook_endpoints/:idDelete an existing webhook endpoint. - PATCHUpdate a Webhook Endpoint
/webhook_endpoints/:idUpdate the properties of an existing webhook endpoint.
widgets
- POSTGenerate a widget token
/widgets/tokenGenerate a widget token for a user, optionally scoped to an organization. When an organization is specified, org-scoped widgets are enabled; omitting it…
workos-connect
- POSTComplete external authentication
/authkit/oauth2/completeCompletes a Standalone Connect login by creating or updating the AuthKit user and returning a redirect_uri your application should redirect to so AuthKit can…
API details
- Base URL
https://api.workos.comhttps://api.workos-test.com- Authentication
- A bearer token in the Authorization header
A bearer token in the Authorization header - Operations
- 273 operations on 188 pathsGET 111POST 89DELETE 39PUT 22PATCH 12
4 marked deprecated - Main resources
- authorization 41pipes 16user-management.users 16connections 14vault 11groups 9audit-logs 8organizations 7user-management.authentication 7user-management.invitations 7
- Response formats
application/json- Description format
- OpenAPI 3.1.1, API version
1.0 - Links
- OpenAPI document · Support
- Listed from
- WorkOS's published OpenAPI description (workos/openapi-spec) (MIT)
How to test the WorkOS API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the WorkOS API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Generate a Portal Link” (POST /portal/generate_link), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the WorkOS API?
WorkOS REST API It is listed under Identity & security and has 273 endpoints.
Who publishes the WorkOS API?
It is listed from WorkOS's public API description (an OpenAPI document), not published by WorkOS on Swastik Codes. Anyone who controls workos.com can claim the profile by adding a DNS TXT record.
What is the base URL of the WorkOS API?
Its description lists 2 base URLs: https://api.workos.com, https://api.workos-test.com. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the WorkOS API?
It accepts 2 methods: A bearer token in the Authorization header; A bearer token in the Authorization header.
How many endpoints does the WorkOS API have?
273 operations on 188 paths (111 GET, 89 POST, 39 DELETE, 22 PUT, 12 PATCH). The largest groups are authorization, pipes, user-management.users, connections.
Is forking the WorkOS API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.