Skip to content

Latest commit

 

History

History
294 lines (199 loc) · 29.2 KB

README.md

File metadata and controls

294 lines (199 loc) · 29.2 KB

OrganizationRoles

Overview

Available Operations

  • List - Get a list of organization roles
  • Create - Create an organization role
  • Get - Retrieve an organization role
  • Update - Update an organization role
  • Delete - Delete an organization role
  • AssignPermission - Assign a permission to an organization role
  • RemovePermission - Remove a permission from an organization role

List

This request returns the list of organization roles for the instance. Results can be paginated using the optional limit and offset query parameters. The organization roles are ordered by descending creation date. Most recent roles will be returned first.

Example Usage

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

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

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

// handle response

Parameters

Parameter Type Required Description Example
Query string ➖ Returns organization roles with ID, name, or key that match the given query.
Uses exact match for organization role ID and partial match for name and key.
OrderBy string ➖ Allows to return organization roles in a particular order.
At the moment, you can order the returned organization roles 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 organization roles 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

ListOrganizationRolesResponse

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 organization role with the given name and permissions for an instance. The key must be unique for the instance and start with the 'org:' prefix, followed by lowercase alphanumeric characters and underscores only. You can optionally provide a description for the role and specify whether it should be included in the initial role set. Organization roles support permissions that can be assigned to control access within the organization.

Example Usage

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

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

CreateOrganizationRoleRequestBody req = new CreateOrganizationRoleRequestBody() {
    Name = "<value>",
    Key = "<key>",
};

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

// handle response

Parameters

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

Response

CreateOrganizationRoleResponse

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

Use this request to retrieve an existing organization role by its ID.

Example Usage

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

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

var res = await sdk.OrganizationRoles.GetAsync(organizationRoleId: "<id>");

// handle response

Parameters

Parameter Type Required Description
OrganizationRoleId string ✔️ The ID of the organization role

Response

GetOrganizationRoleResponse

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 organization role. You can update the name, key, description, and permissions of the role. All parameters are optional - you can update only the fields you want to change. If the role is used as a creator role or domain default role, updating the key will cascade the update to the organization settings.

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.OrganizationRoles.UpdateAsync(
    organizationRoleId: "<id>",
    requestBody: new UpdateOrganizationRoleRequestBody() {}
);

// handle response

Parameters

Parameter Type Required Description
OrganizationRoleId string ✔️ The ID of the organization role to update
RequestBody UpdateOrganizationRoleRequestBody ✔️ N/A

Response

UpdateOrganizationRoleResponse

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 */*

Delete

Deletes the organization role. The role cannot be deleted if it is currently used as the default creator role, domain default role, assigned to any members, or exists in any invitations.

Example Usage

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

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

var res = await sdk.OrganizationRoles.DeleteAsync(organizationRoleId: "<id>");

// handle response

Parameters

Parameter Type Required Description
OrganizationRoleId string ✔️ The ID of the organization role to delete

Response

DeleteOrganizationRoleResponse

Errors

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

AssignPermission

Assigns a permission to an organization role

Example Usage

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

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

var res = await sdk.OrganizationRoles.AssignPermissionAsync(
    organizationRoleId: "<id>",
    permissionId: "<id>"
);

// handle response

Parameters

Parameter Type Required Description
OrganizationRoleId string ✔️ The ID of the organization role
PermissionId string ✔️ The ID of the permission to assign

Response

AssignPermissionToOrganizationRoleResponse

Errors

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

RemovePermission

Removes a permission from an organization role

Example Usage

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

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

var res = await sdk.OrganizationRoles.RemovePermissionAsync(
    organizationRoleId: "<id>",
    permissionId: "<id>"
);

// handle response

Parameters

Parameter Type Required Description
OrganizationRoleId string ✔️ The ID of the organization role
PermissionId string ✔️ The ID of the permission to remove

Response

RemovePermissionFromOrganizationRoleResponse

Errors

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