Access control

RBAC

Choose a built-in role or create a custom one for a teammate.

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.

The slug has to be new, and permissions needs at least one value from the catalog.

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.	Yes

Assign role

Set a member’s role with Assign role. role is the slug, not role_id.

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.