> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/membership/roles/new.md).

# Create a role

Create a role and attach the policies it grants.

**Where:** Membership → Roles → **Add New** · `/projects/<project>/membership/roles/new`

## Before you start

* The policies you want to attach exist — system policies are always there; your own come from [Create a policy](/codemash/cloud/membership/policies/new.md).
* You need the `membership:create` permission on roles.

## Steps

1. Press **Add New**. The screen **Add New Custom Role** opens.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-14c224570b6b8fc2275769fe52aff0ce83ce12ce%2Froles-new-1.png?alt=media" alt="Add New Custom Role with empty Role name and Description and the Attached policies picker listing the system policies"><figcaption><p>The empty form.</p></figcaption></figure>
2. Fill in the form and tick the policies. **Search policies...** filters the list; **Managed only** shows only your own policies.

   | Field             | Required | What it does                                      | Example                                    |
   | ----------------- | -------- | ------------------------------------------------- | ------------------------------------------ |
   | Role name         | yes      | The name of the role. It cannot be changed later. | `content-editor`                           |
   | Description       | no       | What the role is for.                             | `Writes and edits articles; reads orders.` |
   | Attached policies | no       | The policies the role grants (system or yours).   | `content-editing`, `orders-read`           |

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-43ff4e0c872daa4aab2059d771ce2d86cb2741a3%2Froles-new-2.png?alt=media" alt="Role name content-editor, Description Writes and edits articles; reads orders., Managed only ticked, content-editing and orders-read ticked"><figcaption><p>The filled form with two policies ticked.</p></figcaption></figure>
3. Optional: press **Preview** on a policy to see the document it grants.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-791b0f1deac5518f7fdd793ab35e085aa53266ed%2Froles-new-3.png?alt=media" alt="Preview of the content-editing policy: version, pid, name, description and one permission allowing database:Read and database:Update"><figcaption><p>A policy preview.</p></figcaption></figure>
4. Press **Save**.

## Result

Cloud goes back to **Roles** and the new role is in the list as **Custom** with **2** policies. Its id joins the project and the role, for example `pr_5ArJCRo2mJ90H2Fp1oU6ta_nr_IzlTB0VGnUVN5PCM5Ah1H`; this id is what travels when you give the role to a user.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-2533f550d2ce4eeeed95b3b20ded13a833f894b9%2Froles-new-4.png?alt=media" alt="Roles list with content-editor, Custom, 2 policies"><figcaption><p>The new role in the list.</p></figcaption></figure>

## Change or remove it later

* **Edit** — [Edit a role](/codemash/cloud/membership/roles/edit.md): description and policies.
* **Delete** — [Delete a role](/codemash/cloud/membership/roles/delete.md).

## Do it from code

```ts
const pol = 'pol_1oRlzIGnF3lzemVoX1nwyy'; // orders-read
const { id } = await norbix.hub.membership.createRole({
  roleName: 'billing-clerk',
  description: 'Reads invoices.',
  policies: [pol], // policy ids, pol_…
});
console.log(id); // pr_…_nr_…
```

```sh
norbix hub membership role create --roleName drafts-reader --description 'Reads drafts.' --policies pol_55EQ74dP3HciwimFfkM5I1
```

The client setup is on the [Membership page](/codemash/cloud/membership.md#use-it-from-code). API: [Create Role](/codemash/api-reference/membership/roles/create-role.md)