Create a role with the .NET SDK
permitClient.Api.CreateRole() creates a role in the environment that your API key belongs to. This reference is for .NET developers who define role-based access control (RBAC) roles from backend code. After you create a role, assign it to users with AssignRole.
CreateRole signature
public async Task<RoleRead> CreateRole(RoleCreate role)
CreateRole parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
role | RoleCreate | Yes | The role to create. The RoleCreate class is in the PermitSDK.OpenAPI.Models namespace. |
RoleCreate properties
| Property | Type | Required | Description |
|---|---|---|---|
Key | string | Yes | A URL-friendly name of the role (a slug). You use the key to refer to the role in later calls instead of the role ID (a UUID). |
Name | string | Yes | The name of the role. |
Description | string? | No | What the role represents, or which permissions it grants. |
Permissions | ICollection<string>? | No | The permissions the role grants, each in the format <resource-key>:<action-key>, such as document:write. |
Extends | ICollection<string>? | No | The keys of roles that this role extends. The role inherits all the permissions of those roles. |
Build a RoleCreate object named role. The values below create an editor role that can write documents and inherits the permissions of the viewer role:
var role = new RoleCreate
{
Key = "editor",
Name = "Editor",
Description = "the editor role can read and write to documents",
Permissions = new List<string> { "document:write" },
Extends = new List<string> { "viewer" }
};
Example: create a role with CreateRole
The example uses a client named permitClient, created with new Permit(...) as shown in Check permissions with the .NET SDK:
var response = await permitClient.Api.CreateRole(role);
CreateRole return value and errors
On success, CreateRole returns a RoleRead with the role's Key, Id, Name, Description, Permissions, and Extends.
If the Permit API returns an error, CreateRole throws a PermitApiException. The exception's StatusCode property has the HTTP status, such as 422 when a property fails validation, and its Response property has the response body.