Create a role with the Node.js SDK
permit.api.roles.create() creates a role in the Permit.io environment that your Node.js SDK client is connected to. This reference is for backend developers who manage roles from code instead of the Permit dashboard.
Prerequisites
- A
permitclient created with an API key for the environment. See Create a Permit client and Get your API key.
Method signature
| Method | Signature | Status |
|---|---|---|
permit.api.roles.create | create(roleData: RoleCreate): Promise<RoleRead> | Recommended |
permit.api.createRole | createRole(role: RoleCreate): Promise<RoleRead> | Deprecated alias with the same argument |
Parameters
The method takes one argument: a RoleCreate object. Pass the object itself, not a JSON string.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | URL-friendly identifier of the role (a slug). Use the key instead of the role ID in later calls. |
name | string | Yes | Display name of the role. |
description | string | No | What the role represents or which permissions it grants. |
permissions | string[] | No | Permissions granted to the role, each in the format resource:action, for example document:write. |
extends | string[] | No | Keys of roles that this role extends. The role inherits every permission of the listed roles. |
attributes | object | No | Key-value metadata stored on the role. |
Example RoleCreate object for an editor role that extends a viewer role:
{
key: "editor",
name: "Editor",
description: "the editor role can read and write to documents",
permissions: ["document:write"],
extends: ["viewer"]
}
Example
const response = await permit.api.roles.create(role);
Return value
The method resolves to a RoleRead object: the fields you sent, plus id, organization_id, project_id, environment_id, created_at, and updated_at.
If the Permit API returns an error status code, permit.api.roles.create() throws a PermitApiError. The deprecated permit.api.createRole() rethrows the underlying Axios error.