Skip to content

Latest commit

 

History

History
318 lines (223 loc) · 30.3 KB

README.md

File metadata and controls

318 lines (223 loc) · 30.3 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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.RoleSets.ListAsync(
    orderBy: "-created_at",
    limit: 20,
    offset: 10
);

// handle response

Parameters

Parameter Type Required Description Example
Query 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.
OrderBy 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 long ➖ Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.		 20
Offset long ➖ 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

Response

ListRoleSetsResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 400, 401, 403, 422 application/json
Clerk.BackendAPI.Models.Errors.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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Components;
using Clerk.BackendAPI.Models.Operations;
using System.Collections.Generic;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

CreateRoleSetRequestBody req = new CreateRoleSetRequestBody() {
    Name = "<value>",
    DefaultRoleKey = "<value>",
    CreatorRoleKey = "<value>",
    Roles = new List<string>() {
        "<value 1>",
        "<value 2>",
    },
};

var res = await sdk.RoleSets.CreateAsync(req);

// handle response

Parameters

Parameter Type Required Description
request CreateRoleSetRequestBody ✔️ The request object to use for the request.

Response

CreateRoleSetResponse

Errors

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

Get

Retrieves an existing role set by its key or ID.

Example Usage

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Components;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.RoleSets.GetAsync(roleSetKeyOrId: "<id>");

// handle response

Parameters

Parameter Type Required Description
RoleSetKeyOrId string ✔️ The key or ID of the role set

Response

GetRoleSetResponse

Errors

Error Type Status Code Content Type
Clerk.BackendAPI.Models.Errors.ClerkErrors 401, 403, 404 application/json
Clerk.BackendAPI.Models.Errors.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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Components;
using Clerk.BackendAPI.Models.Operations;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.RoleSets.UpdateAsync(
    roleSetKeyOrId: "<id>",
    requestBody: new UpdateRoleSetRequestBody() {}
);

// handle response

Parameters

Parameter Type Required Description
RoleSetKeyOrId string ✔️ The key or ID of the role set to update
RequestBody UpdateRoleSetRequestBody ✔️ N/A

Response

UpdateRoleSetResponse

Errors

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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Components;
using Clerk.BackendAPI.Models.Operations;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.RoleSets.ReplaceAsync(
    roleSetKeyOrId: "<id>",
    requestBody: new ReplaceRoleSetRequestBody() {
        DestRoleSetKey = "<value>",
    }
);

// handle response

Parameters

Parameter Type Required Description
RoleSetKeyOrId string ✔️ The key or ID of the role set to replace
RequestBody ReplaceRoleSetRequestBody ✔️ N/A

Response

ReplaceRoleSetResponse

Errors

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

AddRoles

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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Components;
using Clerk.BackendAPI.Models.Operations;
using System.Collections.Generic;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.RoleSets.AddRolesAsync(
    roleSetKeyOrId: "<id>",
    requestBody: new AddRolesToRoleSetRequestBody() {
        RoleKeys = new List<string>() {
            "<value 1>",
            "<value 2>",
        },
    }
);

// handle response

Parameters

Parameter Type Required Description
RoleSetKeyOrId string ✔️ The key or ID of the role set
RequestBody AddRolesToRoleSetRequestBody ✔️ N/A

Response

AddRolesToRoleSetResponse

Errors

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

ReplaceRole

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

using Clerk.BackendAPI;
using Clerk.BackendAPI.Models.Components;
using Clerk.BackendAPI.Models.Operations;

var sdk = new ClerkBackendApi(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.RoleSets.ReplaceRoleAsync(
    roleSetKeyOrId: "<id>",
    requestBody: new ReplaceRoleInRoleSetRequestBody() {
        RoleKey = "<value>",
        ToRoleKey = "<value>",
    }
);

// handle response

Parameters

Parameter Type Required Description
RoleSetKeyOrId string ✔️ The key or ID of the role set
RequestBody ReplaceRoleInRoleSetRequestBody ✔️ N/A

Response

ReplaceRoleInRoleSetResponse

Errors

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