Skip to content

README.md

Latest commit

 

History

History
323 lines (228 loc) · 27.7 KB

README.md

File metadata and controls

323 lines (228 loc) · 27.7 KB

RoleSets

Overview

Available Operations

list

Returns a list of role sets for the instance. Results can be paginated using the optional limit and offset query parameters. The role sets are ordered by descending creation date by default.

Example Usage

require 'clerk_sdk_ruby'

Models = ::Clerk::Models
s = ::Clerk::OpenAPIClient.new(
  bearer_auth: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.role_sets.list(order_by: '-created_at', limit: 10, offset: 0)

unless res.role_sets.nil?
  # handle response
end

Parameters

Parameter Type Required Description
query Crystalline::Nilable.new(::String) ➖ Returns role sets with ID, name, or key that match the given query.
Uses exact match for role set ID and partial match for name and key.
order_by Crystalline::Nilable.new(::String) ➖ Allows to return role sets in a particular order.
At the moment, you can order the returned role sets by their created_at, name, or key.
In order to specify the direction, you can use the +/- symbols prepended in the property to order by.
For example, if you want role sets to be returned in descending order according to their created_at property, you can use -created_at.
If you don't use + or -, then + is implied.
Defaults to -created_at.
limit Crystalline::Nilable.new(::Integer) ➖ Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
offset Crystalline::Nilable.new(::Integer) ➖ Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.

Response

Crystalline::Nilable.new(Models::Operations::ListRoleSetsResponse)

Errors

Error Type Status Code Content Type
Models::Errors::ClerkErrors 400, 401, 403, 422 application/json
Errors::APIError 4XX, 5XX */*

create

Creates a new role set with the given name and roles. The key must be unique for the instance and start with the 'role_set:' prefix, followed by lowercase alphanumeric characters and underscores only. You must provide at least one role and specify a default role key and creator role key.

Example Usage

require 'clerk_sdk_ruby'

Models = ::Clerk::Models
s = ::Clerk::OpenAPIClient.new(
  bearer_auth: '<YOUR_BEARER_TOKEN_HERE>'
)

req = Models::Operations::CreateRoleSetRequest.new(
  name: '<value>',
  default_role_key: '<value>',
  creator_role_key: '<value>',
  roles: [
    '<value 1>',
    '<value 2>',
  ]
)
res = s.role_sets.create(request: req)

unless res.role_set.nil?
  # handle response
end

Parameters

Parameter Type Required Description
request Models::Operations::CreateRoleSetRequest ✔️ The request object to use for the request.

Response

Crystalline::Nilable.new(Models::Operations::CreateRoleSetResponse)

Errors

Error Type Status Code Content Type
Models::Errors::ClerkErrors 400, 401, 402, 403, 404, 422 application/json
Errors::APIError 4XX, 5XX */*

get

Retrieves an existing role set by its key or ID.

Example Usage

require 'clerk_sdk_ruby'

Models = ::Clerk::Models
s = ::Clerk::OpenAPIClient.new(
  bearer_auth: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.role_sets.get(role_set_key_or_id: '<id>')

unless res.role_set.nil?
  # handle response
end

Parameters

Parameter Type Required Description
role_set_key_or_id ::String ✔️ The key or ID of the role set

Response

Crystalline::Nilable.new(Models::Operations::GetRoleSetResponse)

Errors

Error Type Status Code Content Type
Models::Errors::ClerkErrors 401, 403, 404 application/json
Errors::APIError 4XX, 5XX */*

update

Updates an existing role set. You can update the name, key, description, type, default role, or creator role. All parameters are optional - you can update only the fields you want to change.

Example Usage

require 'clerk_sdk_ruby'

Models = ::Clerk::Models
s = ::Clerk::OpenAPIClient.new(
  bearer_auth: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.role_sets.update(role_set_key_or_id: '<id>', body: Models::Operations::UpdateRoleSetRequestBody.new)

unless res.role_set.nil?
  # handle response
end

Parameters

Parameter Type Required Description
role_set_key_or_id ::String ✔️ The key or ID of the role set to update
body Models::Operations::UpdateRoleSetRequestBody ✔️ N/A

Response

Crystalline::Nilable.new(Models::Operations::UpdateRoleSetResponse)

Errors

Error Type Status Code Content Type
Models::Errors::ClerkErrors 400, 401, 403, 404, 422 application/json
Errors::APIError 4XX, 5XX */*

replace

Replaces a role set with another role set. This is functionally equivalent to deleting the role set but allows for atomic replacement with migration support. Organizations using this role set will be migrated to the destination role set.

Example Usage

require 'clerk_sdk_ruby'

Models = ::Clerk::Models
s = ::Clerk::OpenAPIClient.new(
  bearer_auth: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.role_sets.replace(role_set_key_or_id: '<id>', body: Models::Operations::ReplaceRoleSetRequestBody.new(
  dest_role_set_key: '<value>'
))

unless res.deleted_object.nil?
  # handle response
end

Parameters

Parameter Type Required Description
role_set_key_or_id ::String ✔️ The key or ID of the role set to replace
body Models::Operations::ReplaceRoleSetRequestBody ✔️ N/A

Response

Crystalline::Nilable.new(Models::Operations::ReplaceRoleSetResponse)

Errors

Error Type Status Code Content Type
Models::Errors::ClerkErrors 400, 401, 403, 404, 422 application/json
Errors::APIError 4XX, 5XX */*

add_roles

Adds one or more roles to an existing role set. You can optionally update the default role or creator role when adding new roles.

Example Usage

require 'clerk_sdk_ruby'

Models = ::Clerk::Models
s = ::Clerk::OpenAPIClient.new(
  bearer_auth: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.role_sets.add_roles(role_set_key_or_id: '<id>', body: Models::Operations::AddRolesToRoleSetRequestBody.new(
  role_keys: [
    '<value 1>',
    '<value 2>',
  ]
))

unless res.role_set.nil?
  # handle response
end

Parameters

Parameter Type Required Description
role_set_key_or_id ::String ✔️ The key or ID of the role set
body Models::Operations::AddRolesToRoleSetRequestBody ✔️ N/A

Response

Crystalline::Nilable.new(Models::Operations::AddRolesToRoleSetResponse)

Errors

Error Type Status Code Content Type
Models::Errors::ClerkErrors 400, 401, 403, 404, 422 application/json
Errors::APIError 4XX, 5XX */*

replace_role

Replaces a role in a role set with another role. This atomically removes the source role and reassigns any members to the destination role.

Example Usage

require 'clerk_sdk_ruby'

Models = ::Clerk::Models
s = ::Clerk::OpenAPIClient.new(
  bearer_auth: '<YOUR_BEARER_TOKEN_HERE>'
)
res = s.role_sets.replace_role(role_set_key_or_id: '<id>', body: Models::Operations::ReplaceRoleInRoleSetRequestBody.new(
  role_key: '<value>',
  to_role_key: '<value>'
))

unless res.role_set.nil?
  # handle response
end

Parameters

Parameter Type Required Description
role_set_key_or_id ::String ✔️ The key or ID of the role set
body Models::Operations::ReplaceRoleInRoleSetRequestBody ✔️ N/A

Response

Crystalline::Nilable.new(Models::Operations::ReplaceRoleInRoleSetResponse)

Errors

Error Type Status Code Content Type
Models::Errors::ClerkErrors 400, 401, 403, 404, 422 application/json
Errors::APIError 4XX, 5XX */*