Skip to content

README.md

Latest commit

 

History

History
336 lines (228 loc) · 46.8 KB

README.md

File metadata and controls

336 lines (228 loc) · 46.8 KB
Raw

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

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.role_sets.list(query="<value>", order_by="-created_at", limit=20, offset=10)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description Example
query Optional[str] ➖ 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 Optional[str] ➖ 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 Optional[int] ➖ Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.		 20
offset Optional[int] ➖ Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.		 10
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.RoleSets

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 403, 422 application/json
models.SDKError 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

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.role_sets.create(name="<value>", default_role_key="<value>", creator_role_key="<value>", roles=[
        "<value 1>",
    ], key="<key>", description="coarse minor like whopping jazz concerning questioningly loose", type_=clerk_backend_api.CreateRoleSetType.CUSTOM)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
name str ✔️ The name of the new role set
default_role_key str ✔️ The key of the role to use as the default role for new organization members.
Must be one of the roles in the roles array.
creator_role_key str ✔️ The key of the role to assign to organization creators.
Must be one of the roles in the roles array.
roles List[str] ✔️ Array of role keys to include in the role set.
Must contain at least one role and no more than 10 roles.
key Optional[str] ➖ A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores.
If not provided, a key will be generated from the name.
description OptionalNullable[str] ➖ Optional description for the role set
type Optional[models.CreateRoleSetType] ➖ The type of the role set. "initial" role sets are the default for new organizations.
Only one role set can be "initial" per instance.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.RoleSet

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 402, 403, 404, 422 application/json
models.SDKError 4XX, 5XX */*

get

Retrieves an existing role set by its key or ID.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.role_sets.get(role_set_key_or_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
role_set_key_or_id str ✔️ The key or ID of the role set
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.RoleSet

Errors

Error Type Status Code Content Type
models.ClerkErrors 401, 403, 404 application/json
models.SDKError 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

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.role_sets.update(role_set_key_or_id="<id>", name="<value>", key=None, description="airbus atop ouch gadzooks anti talkative mould", type_=clerk_backend_api.UpdateRoleSetType.INITIAL, default_role_key="<value>", creator_role_key="<value>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
role_set_key_or_id str ✔️ The key or ID of the role set to update
name OptionalNullable[str] ➖ The new name for the role set
key OptionalNullable[str] ➖ A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores.
description OptionalNullable[str] ➖ Optional description for the role set
type OptionalNullable[models.UpdateRoleSetType] ➖ Set to "initial" to make this the default role set for new organizations.
Only one role set can be "initial" per instance; setting this will change any existing initial role set to "custom".
default_role_key OptionalNullable[str] ➖ The key of the role to use as the default role for new organization members.
Must be an existing role in the role set.
creator_role_key OptionalNullable[str] ➖ The key of the role to assign to organization creators.
Must be an existing role in the role set.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.RoleSet

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 403, 404, 422 application/json
models.SDKError 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

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.role_sets.replace(role_set_key_or_id="<id>", dest_role_set_key="<value>", reassignment_mappings={
        "key": "<value>",
        "key1": "<value>",
        "key2": "<value>",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
role_set_key_or_id str ✔️ The key or ID of the role set to replace
dest_role_set_key str ✔️ The key of the destination role set
reassignment_mappings Dict[str, str] ➖ Mappings from source role keys to destination role keys.
Required if members have roles that need to be reassigned.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.DeletedObject

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 403, 404, 422 application/json
models.SDKError 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

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.role_sets.add_roles(role_set_key_or_id="<id>", role_keys=[
        "<value 1>",
        "<value 2>",
    ], default_role_key="<value>", creator_role_key="<value>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
role_set_key_or_id str ✔️ The key or ID of the role set
role_keys List[str] ✔️ Array of role keys to add to the role set.
Must contain at least one role and no more than 10 roles.
default_role_key Optional[str] ➖ Optionally update the default role to one of the newly added roles.
creator_role_key Optional[str] ➖ Optionally update the creator role to one of the newly added roles.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.RoleSet

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 403, 404, 422 application/json
models.SDKError 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

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.role_sets.replace_role(role_set_key_or_id="<id>", role_key="<value>", to_role_key="<value>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
role_set_key_or_id str ✔️ The key or ID of the role set
role_key str ✔️ The key of the role to remove from the role set
to_role_key str ✔️ The key of the role to reassign members to
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.RoleSet

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 403, 404, 422 application/json
models.SDKError 4XX, 5XX */*