# RBAC

Built-in and custom roles, and the permissions a teammate can use in Blnk Cloud.

This feature is only available in the Enterprise version

A role is the set of permissions a teammate has in the organization. Blnk checks those permissions on each request, not the name of the role.

Use a built-in role, or create a custom one when that is more access than the person needs. 

## Built-in roles

Every organization already has these roles. You can assign them, and you cannot change or delete them.

| Role | What they can do |
| :-- | :-- |
| `admin` | Everything in the organization, including billing reports. |
| `operator` | Day-to-day operations: instances, data, the proxy, transactions, agents, and alerts. |
| `analyst` | Read and monitor ledger data. |
| `investigator` | Work across alerts, anomalies, and ledger data. |

## Who can manage roles

Listing roles, changing them, and assigning them are separate permissions. 

An admin has `roles.write` and `members.write`, so they can do all three.

| Action | Permission |
| :-- | :-- |
| List roles | `roles.read` |
| Create, update, or delete a role | `roles.write` |
| Assign a role | `members.write` |

## Create a role

Create a custom role with [Create role](/reference/create-role). 

The slug has to be new, and `permissions` needs at least one value from the [catalog](#permission-catalog).

```bash Create role wrap
curl -X POST "https://api.cloud.blnkfinance.com/organizations/roles" \
  -H "X-blnk-key: CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "finance-ops",
    "name": "Finance Ops",
    "description": "Read billing and ledger data",
    "permissions": ["billing.read", "data.read", "instances.read", "org.read"]
  }'
```

| Field | Description | Required |
| :-- | :-- | :-- |
| `slug` | Slug for the role, such as `finance-ops`. Must not be a built-in role. | Yes |
| `name` | Display name of the role. | Yes |
| `description` | What the role is for. | No |
| `permissions` | Permissions on the role. At least one, each from the [catalog](#permission-catalog). | Yes |

## Assign role

Set a member's role with [Assign role](/reference/assign-role). `role` is the slug, not `role_id`.

```bash Assign role
curl -X PUT "https://api.cloud.blnkfinance.com/organizations/members/YOUR_USER_ID/role" \
  -H "X-blnk-key: CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role":"finance-ops"
    }'
```

| Field | Description | Required |
| :-- | :-- | :-- |
| `user_id` | Id of the member. This is the path parameter. | Yes |
| `role` | Slug of the role, such as `admin` or `finance-ops`. | Yes |

## Permission catalog

A custom role takes its permissions from this list. 

A read needs the matching `*.read` permission, a change needs `*.write`, and a usage billing report needs `billing.report`.

| Permission | What it allows |
| :-- | :-- |
| `instances.read` | Read instances. |
| `instances.write` | Create, update, or delete instances. |
| `data.read` | Read data. |
| `data.write` | Create, update, or delete data. |
| `transactions.create` | Create transactions. |
| `transactions.metadata.write` | Update transaction metadata. |
| `transactions.status.write` | Commit or void inflight transactions. |
| `transactions.refund` | Refund transactions. |
| `users.read` | Read users. |
| `users.write` | Create or update users. |
| `users.delete` | Delete users. |
| `org.read` | Read organization details. |
| `org.write` | Update organization details. |
| `org.delete` | Delete organizations. |
| `members.read` | Read organization members. |
| `members.write` | Manage organization members. |
| `roles.read` | Read organization roles. |
| `roles.write` | Manage organization roles. |
| `billing.read` | Read billing details. |
| `billing.write` | Manage billing. |
| `billing.report` | Generate usage billing reports. |
| `audit.read` | Read audit logs. |
| `alerts.read` | Read alerts. |
| `alerts.write` | Manage alerts. |
| `alerts.delete` | Delete alerts. |
| `anomalies.read` | Read anomalies. |
| `anomalies.write` | Manage anomalies. |
| `anomalies.delete` | Delete anomalies. |
| `deployments.read` | Read deployments. |
| `deployments.write` | Manage deployments. |
| `mcp.read` | Read MCP resources. |
| `mcp.write` | Manage MCP resources. |
| `apps.read` | Read apps. |
| `apps.write` | Create or update apps. |
| `proxy.read` | Read proxy resources. |
| `proxy.write` | Manage proxy resources. |
| `agents.read` | Read agents. |
| `agents.write` | Manage agents. |

<RelatedTopics
  items={[
    { title: "Team members", href: "/access-control/team" },
    { title: "Create role", href: "/reference/create-role" },
    { title: "Assign role", href: "/reference/assign-role" },
    { title: "List roles", href: "/reference/list-roles" },
  ]}
/>