@spec add_environment_role_permission(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Add a permission to an environment role

Add a single permission to an environment role. If the permission is already assigned to the role, this operation has no effect.

Parameters

• slug — The slug of the environment role.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec add_organization_role_permission(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) :: {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Add a permission to a custom role

Add a single permission to a custom role. If the permission is already assigned to the role, this operation has no effect.

Parameters

• organization_id — The ID of the organization.
• slug — The slug of the role.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec assign_role(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.UserRoleAssignment.t()} | {:error, WorkOS.Error.error()}

Assign a role

Assign a role to an organization membership on a specific resource.

Parameters

• organization_membership_id — The ID of the organization membership.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec check(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.AuthorizationCheck.t()} | {:error, WorkOS.Error.error()}

Check authorization

Check if an organization membership has a specific permission on a resource. Supports identification by resource_id OR by resource_external_id + resource_type_slug.

Parameters

• organization_membership_id — The ID of the organization membership to check.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec create_environment_role(WorkOS.Client.t(), map(), keyword()) ::
  {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Create an environment role

Create a new environment role.

Parameters

• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec create_group_role_assignment(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.GroupRoleAssignment.t()} | {:error, WorkOS.Error.error()}

Assign a role to a group

Assign a role to a group on a specific resource.

Parameters

• group_id — The ID of the group.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec create_organization_role(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Create a custom role

Create a new custom role for this organization.

Parameters

• organization_id — The ID of the organization.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec create_permission(WorkOS.Client.t(), map(), keyword()) ::
  {:ok, WorkOS.Permission.t()} | {:error, WorkOS.Error.error()}

Create a permission

Create a new permission in your WorkOS environment. The permission can then be assigned to environment roles and custom roles.

Parameters

• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec create_resource(WorkOS.Client.t(), map(), keyword()) ::
  {:ok, WorkOS.AuthorizationResource.t()} | {:error, WorkOS.Error.error()}

Create an authorization resource

Create a new authorization resource.

Parameters

• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec delete_group_role_assignment(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  keyword()
) ::
  {:ok, term()} | {:error, WorkOS.Error.error()}

Remove a group role assignment

Remove a specific role assignment from a group by its ID.

Parameters

• group_id — The ID of the group.
• role_assignment_id — The ID of the group role assignment to remove.
• opts — per-request options (see WorkOS.Client.request/5)

@spec delete_group_role_assignments(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, WorkOS.Error.error()}

Remove group role assignments by criteria

Remove role assignments from a group that match the provided criteria. Returns 404 when no matching active assignment is found.

Parameters

• group_id — The ID of the group.
• params — query parameters
• opts — per-request options (see WorkOS.Client.request/5)

@spec delete_organization_role(WorkOS.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, WorkOS.Error.error()}

Delete a custom role

Delete an existing custom role.

Parameters

• organization_id — The ID of the organization.
• slug — The slug of the role.
• opts — per-request options (see WorkOS.Client.request/5)

@spec delete_permission(WorkOS.Client.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, WorkOS.Error.error()}

Delete a permission

Delete an existing permission. System permissions cannot be deleted.

Parameters

• slug — A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
• opts — per-request options (see WorkOS.Client.request/5)

@spec delete_resource(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, WorkOS.Error.error()}

Delete an authorization resource

Delete an authorization resource and all its descendants.

Parameters

• resource_id — The ID of the authorization resource.
• params — query parameters: :cascade_delete
• opts — per-request options (see WorkOS.Client.request/5)

@spec delete_resource_by_external_id(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) :: {:ok, term()} | {:error, WorkOS.Error.error()}

Delete an authorization resource by external ID

Delete an authorization resource by organization, resource type, and external ID. This also deletes all descendant resources.

Parameters

• organization_id — The ID of the organization that owns the resource.
• resource_type_slug — The slug of the resource type.
• external_id — An identifier you provide to reference the resource in your system.
• params — query parameters: :cascade_delete
• opts — per-request options (see WorkOS.Client.request/5)

@spec get_environment_role(WorkOS.Client.t(), String.t(), keyword()) ::
  {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Get an environment role

Get an environment role by its slug.

Parameters

• slug — The slug of the environment role.
• opts — per-request options (see WorkOS.Client.request/5)

@spec get_group_role_assignment(WorkOS.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, WorkOS.GroupRoleAssignment.t()} | {:error, WorkOS.Error.error()}

Get a group role assignment

Get a specific role assignment for a group by its ID.

Parameters

• group_id — The ID of the group.
• role_assignment_id — The ID of the group role assignment.
• opts — per-request options (see WorkOS.Client.request/5)

@spec get_organization_role(WorkOS.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Get a custom role

Retrieve a role that applies to an organization by its slug. This can return either an environment role or a custom role.

Parameters

• organization_id — The ID of the organization.
• slug — The slug of the role.
• opts — per-request options (see WorkOS.Client.request/5)

@spec get_permission(WorkOS.Client.t(), String.t(), keyword()) ::
  {:ok, WorkOS.AuthorizationPermission.t()} | {:error, WorkOS.Error.error()}

Get a permission

Retrieve a permission by its unique slug.

Parameters

• slug — A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
• opts — per-request options (see WorkOS.Client.request/5)

@spec get_resource(WorkOS.Client.t(), String.t(), keyword()) ::
  {:ok, WorkOS.AuthorizationResource.t()} | {:error, WorkOS.Error.error()}

Get a resource

Retrieve the details of an authorization resource by its ID.

Parameters

• resource_id — The ID of the authorization resource.
• opts — per-request options (see WorkOS.Client.request/5)

@spec get_resource_by_external_id(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, WorkOS.AuthorizationResource.t()} | {:error, WorkOS.Error.error()}

Get a resource by external ID

Retrieve 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 your system and need to fetch the full resource details.

Parameters

• organization_id — The ID of the organization that owns the resource.
• resource_type_slug — The slug of the resource type.
• external_id — An identifier you provide to reference the resource in your system.
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_effective_permissions(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) ::
  {:ok, WorkOS.Page.t(WorkOS.AuthorizationPermission.t())}
  | {:error, WorkOS.Error.error()}

List effective permissions for an organization membership on a resource

Returns all permissions the organization membership effectively has on a resource, including permissions inherited through roles assigned to ancestor resources.

Parameters

• organization_membership_id — The ID of the organization membership.
• resource_id — The ID of the authorization resource.
• params — query parameters: :before, :after_, :limit, :order
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_effective_permissions_by_external_id(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) ::
  {:ok, WorkOS.Page.t(WorkOS.AuthorizationPermission.t())}
  | {:error, WorkOS.Error.error()}

List effective permissions for an organization membership on a resource by external ID

Returns all permissions the organization membership effectively has on a resource identified by its external ID, including permissions inherited through roles assigned to ancestor resources.

Parameters

• organization_membership_id — The ID of the organization membership.
• resource_type_slug — The slug of the resource type.
• external_id — An identifier you provide to reference the resource in your system.
• params — query parameters: :before, :after_, :limit, :order
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_environment_roles(
  WorkOS.Client.t(),
  keyword()
) :: {:ok, WorkOS.RoleList.t()} | {:error, WorkOS.Error.error()}

List environment roles

List all environment roles in priority order.

Parameters

• opts — per-request options (see WorkOS.Client.request/5)

@spec list_group_role_assignments(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.Page.t(WorkOS.GroupRoleAssignment.t())}
  | {:error, WorkOS.Error.error()}

List role assignments for a group

List all role assignments granted to a group. Each assignment represents a role granted to the group on a resource.

Parameters

• group_id — The ID of the group.
• params — query parameters: :before, :after_, :limit, :order
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_memberships_for_resource(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.Page.t(WorkOS.UserOrganizationMembershipBaseListData.t())}
  | {:error, WorkOS.Error.error()}

List organization memberships for resource

Returns all organization memberships that have a specific permission on a resource instance. This is useful for answering "Who can access this resource?".

Parameters

• resource_id — The ID of the authorization resource.
• params — query parameters: :before, :after_, :limit, :order, :permission_slug, :assignment
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_memberships_for_resource_by_external_id(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) ::
  {:ok, WorkOS.Page.t(WorkOS.UserOrganizationMembershipBaseListData.t())}
  | {:error, WorkOS.Error.error()}

List memberships for a resource by external ID

Returns all organization memberships that have a specific permission on a resource, using the resource's external ID. This is useful for answering "Who can access this resource?" when you only have the external ID.

Parameters

• organization_id — The ID of the organization that owns the resource.
• resource_type_slug — The slug of the resource type this resource belongs to.
• external_id — An identifier you provide to reference the resource in your system.
• params — query parameters: :before, :after_, :limit, :order, :permission_slug, :assignment
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_organization_roles(WorkOS.Client.t(), String.t(), keyword()) ::
  {:ok, WorkOS.RoleList.t()} | {:error, WorkOS.Error.error()}

List custom roles

Get a list of all roles that apply to an organization. This includes both environment roles and custom roles, returned in priority order.

Parameters

• organization_id — The ID of the organization.
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_permissions(WorkOS.Client.t(), map(), keyword()) ::
  {:ok, WorkOS.Page.t(WorkOS.AuthorizationPermission.t())}
  | {:error, WorkOS.Error.error()}

List permissions

Get a list of all permissions in your WorkOS environment.

Parameters

• params — query parameters: :before, :after_, :limit, :order
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_resources(WorkOS.Client.t(), map(), keyword()) ::
  {:ok, WorkOS.Page.t(WorkOS.AuthorizationResource.t())}
  | {:error, WorkOS.Error.error()}

List resources

Get a paginated list of authorization resources.

Parameters

• params — query parameters: :before, :after_, :limit, :order, :organization_id, :resource_type_slug, :resource_external_id, :parent_resource_id, :parent_resource_type_slug, :parent_external_id
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_resources_for_membership(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.Page.t(WorkOS.AuthorizationResource.t())}
  | {:error, WorkOS.Error.error()}

List resources for organization membership

Returns all child resources of a parent resource where the organization membership has a specific permission. This is useful for resource discovery—answering "What projects can this user access in this workspace?"

You must provide either parent_resource_id or both parent_resource_external_id and parent_resource_type_slug to identify the parent resource.

Parameters

• organization_membership_id — The ID of the organization membership.
• params — query parameters: :before, :after_, :limit, :order, :permission_slug, :parent_resource_id, :parent_resource_type_slug, :parent_resource_external_id
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_role_assignments(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.Page.t(WorkOS.UserRoleAssignment.t())}
  | {:error, WorkOS.Error.error()}

List role assignments

List all role assignments for an organization membership. This returns all roles that have been assigned to the user on resources, including organization-level and sub-resource roles.

Parameters

• organization_membership_id — The ID of the organization membership.
• params — query parameters: :before, :after_, :limit, :order, :resource_id, :resource_external_id, :resource_type_slug
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_role_assignments_for_resource(
  WorkOS.Client.t(),
  String.t(),
  map(),
  keyword()
) ::
  {:ok, WorkOS.Page.t(WorkOS.UserRoleAssignment.t())}
  | {:error, WorkOS.Error.error()}

List role assignments for a resource

List all role assignments granted on a specific resource instance. Each assignment includes the organization membership it was granted to.

Parameters

• resource_id — The ID of the authorization resource.
• params — query parameters: :before, :after_, :limit, :order, :role_slug
• opts — per-request options (see WorkOS.Client.request/5)

@spec list_role_assignments_for_resource_by_external_id(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) ::
  {:ok, WorkOS.Page.t(WorkOS.UserRoleAssignment.t())}
  | {:error, WorkOS.Error.error()}

List role assignments for a resource by external ID

List all role assignments granted on a resource, identified by its external ID. Each assignment includes the organization membership it was granted to.

Parameters

• organization_id — The ID of the organization that owns the resource.
• resource_type_slug — The slug of the resource type.
• external_id — An identifier you provide to reference the resource in your system.
• params — query parameters: :before, :after_, :limit, :order, :role_slug
• opts — per-request options (see WorkOS.Client.request/5)

@spec remove_organization_role_permission(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Remove a permission from a custom role

Remove a single permission from a custom role by its slug.

Parameters

• organization_id — The ID of the organization.
• slug — The slug of the role.
• permission_slug — The slug of the permission to remove.
• opts — per-request options (see WorkOS.Client.request/5)

@spec remove_role(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, term()} | {:error, WorkOS.Error.error()}

Remove a role assignment

Remove a role assignment by role slug and resource.

Parameters

• organization_membership_id — The ID of the organization membership.
• params — query parameters
• opts — per-request options (see WorkOS.Client.request/5)

@spec remove_role_assignment(WorkOS.Client.t(), String.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, WorkOS.Error.error()}

Remove a role assignment by ID

Remove a role assignment using its ID.

Parameters

• organization_membership_id — The ID of the organization membership.
• role_assignment_id — The ID of the role assignment to remove.
• opts — per-request options (see WorkOS.Client.request/5)

@spec set_environment_role_permissions(
  WorkOS.Client.t(),
  String.t(),
  map(),
  keyword()
) ::
  {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Set permissions for an environment role

Replace all permissions on an environment role with the provided list.

Parameters

• slug — The slug of the environment role.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec set_organization_role_permissions(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) :: {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Set permissions for a custom role

Replace all permissions on a custom role with the provided list.

Parameters

• organization_id — The ID of the organization.
• slug — The slug of the role.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec update_environment_role(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Update an environment role

Update an existing environment role.

Parameters

• slug — The slug of the environment role.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec update_group_role_assignments(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.GroupRoleAssignmentList.t()} | {:error, WorkOS.Error.error()}

Replace all role assignments for a group

Replace all role assignments for a group with the provided list. Existing assignments not in the list will be removed.

Parameters

• group_id — The ID of the group.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec update_organization_role(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) ::
  {:ok, WorkOS.Role.t()} | {:error, WorkOS.Error.error()}

Update a custom role

Update an existing custom role. Only the fields provided in the request body will be updated.

Parameters

• organization_id — The ID of the organization.
• slug — The slug of the role.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec update_permission(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.AuthorizationPermission.t()} | {:error, WorkOS.Error.error()}

Update a permission

Update an existing permission. Only the fields provided in the request body will be updated.

Parameters

• slug — A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec update_resource(WorkOS.Client.t(), String.t(), map(), keyword()) ::
  {:ok, WorkOS.AuthorizationResource.t()} | {:error, WorkOS.Error.error()}

Update a resource

Update an existing authorization resource.

Parameters

• resource_id — The ID of the authorization resource.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)

@spec update_resource_by_external_id(
  WorkOS.Client.t(),
  String.t(),
  String.t(),
  String.t(),
  map(),
  keyword()
) :: {:ok, WorkOS.AuthorizationResource.t()} | {:error, WorkOS.Error.error()}

Update a resource by external ID

Update an existing authorization resource using its external ID.

Parameters

• organization_id — The ID of the organization that owns the resource.
• resource_type_slug — The slug of the resource type.
• external_id — An identifier you provide to reference the resource in your system.
• params — request body map
• opts — per-request options (see WorkOS.Client.request/5)