---
title: "How do I create a role?"
slug: "how-do-i-create-a-role"
updated: 2024-09-20T14:20:35Z
published: 2024-09-20T14:20:35Z
canonical: "support.lusid.com/how-do-i-create-a-role"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I create a role?

Providing you are a LUSID user with sufficient privileges, you can create a [role](/v1/docs/what-is-a-role) to model a real-world job function or responsibility.

> **Note:** If you are the LUSID domain owner, you are automatically assigned the built-in `lusid-administrator` role, which has all the permissions necessary to perform the operations in this article.

Once created, you should assign one or more [policies](/v1/docs/what-are-a-policy-and-a-policy-collection) to the role, and then assign the role to one or more [users](/v1/docs/what-are-a-personal-user-and-a-service-user).

## Using the LUSID web app

1. Sign in to the [LUSID web app](https://www.lusid.com/app) using the credentials of a LUSID administrator.
2. From the left-hand menu, select **Identity and Access > Roles**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/926d844b-7572-46ec-932b-9d5762a874ed.png)
3. On the **Roles** dashboard, click the **Create role** button: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/919323fb-360d-4637-9984-fa6be2834c59.png)
4. Specify a unique **Code** for the role, and optionally assign suitable policies from the **Policies > Choose** dropdown (you can also do this later): ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/91de62f3-cfc4-4971-a094-d364751ac205.png)
5. Click the **Create** button to create the role.

## Using the Identity API and then the Access API

You can create a role using the [Identity API](https://www.lusid.com/docs/api/identity/intro) and then the [Access API](https://www.lusid.com/docs/api/access/intro) (or *vice versa*). We have different APIs for identity management and access control to securely separate these concerns; roles are the link between the two systems.

You must create the role in both systems; it does not matter which you do first.

> **Note**: If you want to delete a role, you must also do so in both systems.

1. [Obtain an API access token](/v1/docs/how-do-i-obtain-and-use-a-short-lived-api-access-token-from-okta).
2. Call the Identity [CreateRole](https://www.lusid.com/docs/api/identity/endpoints/roles/CreateRole) API, passing in your access token and a name and description. For example:

```json
curl -X POST "https://<your-domain>.lusid.com/identity/api/roles"
   -H "Authorization: Bearer <your-access-token>"
   -H "Content-Type: application/json"
   -d "{'name':'portfolio-manager-role','description':'A role representing the manager of a portfolio'}"
```

The response contains an automatically-generated scope and code that together uniquely identify the role:

```json
{
   "id": "00gbpzy5scH1crv8I2p7",
   "roleId": {
      "scope": "default",
      "code": "portfolio-manager-role"
    },
   "name": "portfolio-manager-role",
   "description": "A role representing the manager of a portfolio"
}
```
3. Call the Access [CreateRole](https://www.lusid.com/docs/api/access/endpoints/roles/CreateRole) API, passing in the access token and the code for the role. For example:

```json
curl -X POST "https://<your-domain>.lusid.com/access/api/roles"
   -H "Authorization: Bearer <your-access-token>"
   -H "Content-Type: application/json"
   -d "{'code':'portfolio-manager-role','resource':{'policyIdRoleResource':{'policies':[],'policyCollections':[]}},'when':{}}"
```

The role now exists in both systems. You can:

- Assign the role to one or more users using the Identity API.
- Assign one or more policies to the role using the Access API. [See how to perform these operations](/v1/docs/how-do-i-assign-policies-roles-and-users-to-each-other-using-the-api).

## Setting precedence for a role

A role has a precedence that determines which policies take effect in the event of a conflict.

For example, if a user is assigned two roles, and they are ranked with respect to one another as follows:

1. `portfolio-manager-us`
2. `data-controller`

...then the policies in `portfolio-manager-us` take precedence over the policies in `data-controller` should they conflict.

To set precedence, use the ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/c8f46e69-2504-426c-a85f-06b6055a5f05.png) icon to move the table row for a role up or down in the **Roles** dashboard:

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/854dd2de-f37f-41cb-9c22-26f67edebcb5.png)

Note it’s not possible to reset the precedence of the `lusid-administrator` role (which is always ranked #1).