Update a role with the Node.js SDK
permit.api.roles.update() changes the fields of an existing 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.
Prerequisites
- A
permitclient created with an API key for the environment. See Create a Permit client. - An existing role. See Create a role with the Node.js SDK.
Method signature
| Method | Signature | Status |
|---|---|---|
permit.api.roles.update | update(roleKey: string, roleData: RoleUpdate): Promise<RoleRead> | Recommended |
permit.api.updateRole | updateRole(roleId: string, role: RoleUpdate): Promise<RoleRead> | Deprecated alias with the same arguments |
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
roleKey | string | Yes | Key or ID of the role to update. |
roleData | RoleUpdate | Yes | Object with the fields to change. Pass the object itself, not a JSON string. |
The RoleUpdate object accepts these fields. The role key can't be changed.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | 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. |
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 RoleUpdate object:
{
name: "Editor",
description: "the editor role can read and write to documents",
permissions: ["document:write"],
extends: []
}
Example
const response = await permit.api.roles.update(roleKey, role);
Return value
The method resolves to the updated RoleRead object, including key, id, name, permissions, extends, and updated_at.
If the role doesn't exist or the Permit API returns another error status code, permit.api.roles.update() throws a PermitApiError. The deprecated permit.api.updateRole() rethrows the underlying Axios error.