Create Role
POST
/v1/account/roles
Create a custom role in your active account with its own permission matrix. A role bundles a yes/no decision for each of four actions on each resource; once created you assign it to members (or attach it to an invitation) to grant them exactly that access.
Permission required
Requires roles:write (recall that write means create). The account owner always passes — the owner holds every permission implicitly.
Resources you can grant
Each permission entry targets one resource by its key. The full set is:
Traffic inspection / logging.
Account members and invitations.
Roles themselves (this resource).
The four verbs
For each resource you set four independent booleans. They do not imply one another — granting can_update does not grant can_read.
View / list the resource.
Create new instances. write is the create verb.
Modify existing instances.
Request body
Role display name. 1–100 characters. Must be unique within the account.
Optional free-text description.
The matrix. Each element is { "resource", "can_read", "can_write", "can_update", "can_delete" }. List only the resources you want to grant — omitted resources default to no access. Each resource may appear at most once, and the key must be one of the resource keys above (an unknown or duplicate key is rejected).
Response (201 Created)
Returns the created role under role, including its uuid, account_uuid and the stored permissions matrix (each row carries role_uuid).
Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.
Errors
Missing name, name too long, or an unknown / duplicate resource key in permissions.
No active account, or your role lacks roles:write.
A role with that name already exists in the account.
Failed to create the role.
curl -X POST "https://api.ngris.com/v1/account/roles" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"name": "Billing Admin",
"description": "Manage billing only",
"permissions": [
{"resource": "billing", "can_read": true, "can_write": true, "can_update": true, "can_delete": false},
{"resource": "endpoints", "can_read": true, "can_write": false, "can_update": false, "can_delete": false}
]
}'
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
role = client._post_raw("/account/roles", {
"name": "Billing Admin",
"description": "Manage billing only",
"permissions": [
{"resource": "billing", "can_read": True, "can_write": True, "can_update": True, "can_delete": False},
{"resource": "endpoints", "can_read": True, "can_write": False, "can_update": False, "can_delete": False},
],
})
print(role["role"]["uuid"])
{
"role": {
"uuid": "019a9e4e-0c47-7ca0-a55a-00a4a0094d0e",
"account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
"name": "Billing Admin",
"description": "Manage billing only",
"is_builtin": false,
"member_count": 0,
"permissions": [
{
"role_uuid": "019a9e4e-0c47-7ca0-a55a-00a4a0094d0e",
"resource": "billing",
"can_read": true,
"can_write": true,
"can_update": true,
"can_delete": false
},
{
"role_uuid": "019a9e4e-0c47-7ca0-a55a-00a4a0094d0e",
"resource": "endpoints",
"can_read": true,
"can_write": false,
"can_update": false,
"can_delete": false
}
]
}
}