Create Role
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:
endpoints
Tunnel endpoints.
domains
Custom domains.
certs
TLS certificates.
ips
IP allow/deny entries.
firewall
Firewall policies.
rate_limits
Rate-limit policies.
traffic_inspector
Traffic inspection / logging.
members
Account members and invitations.
roles
Roles themselves (this resource).
settings
Account settings.
billing
Plan and billing.
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.
can_read read
View / list the resource.
can_write write = create
Create new instances.
write is the create verb.can_update update
Modify existing instances.
can_delete delete
Remove instances.
Request body
name string Req
Role display name. 1–100 characters. Must be unique within the account.
description string
Optional free-text description.
permissions array
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 assigned id and the stored permissions matrix.
Errors
400 Bad Request
Missing
name, name too long, or an unknown / duplicate resource key in permissions.401 Unauthorized
Missing or invalid auth.
403 Forbidden
No active account, or your role lacks
roles:write.409 Conflict
A role with that name already exists in the account.
500
Failed to create the role.
Request
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}
]
}'
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
role = client.account.create_role(
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"]["id"])
Response — 201 Created
{
"role": {
"id": 12,
"name": "Billing Admin",
"description": "Manage billing only",
"is_builtin": false,
"member_count": 0,
"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
}
]
}
}