Creates a role.
Why a caller cannot grant what they do not hold
Otherwise roles:write is every permission. An account holding only that
could mint a role granting users:delete and join it. The check makes it
mean "may hand out what I have".
Errors
400 when the name or a permission is not usable, 401 when nothing was
signed in, 403 when the caller may not write roles, used a bearer token,
or asked for a permission they do not hold, 409 when the name is taken,
404 when this instance has no administration.
sessiontessera_session<token>Set by POST /auth/login. A browser sends it automatically; it is HttpOnly, so page scripts cannot read or set it.
application/json- body
Body of POST /admin/roles and PUT /admin/roles/{id}.
description?|What it is for.
max_file_bytes?|Largest single file accounts in this role may send.
Omit or send null to fall back to server.max_body_bytes; send 0
for no limit of its own. server.max_body_bytes still applies on top,
so this can only lower it.
int640 <= valuename*stringWhat to call it.
permissions*array<string>Everything it should allow, as resource:verb strings.
The whole set, not a change to it, so two operators editing the same role cannot interleave their edits into a set neither chose. The last one to press save wins, visibly.
quota_bytes?|How much storage each account in this role may hold.
Omit or send null to fall back to the instance-wide ceiling; send 0
for no ceiling at all. Those are different: null follows
storage.max_total_bytes as it changes, 0 ignores it.
int640 <= valueThe role as it now stands
application/json- response
One role, as the API describes it.
created_at*stringWhen it was created, RFC 3339.
description?|What it is for, in the operator's own words.
id*stringStable identifier.
is_system*booleanWhether it is one of the two the instance was seeded with.
Those cannot be deleted: an instance whose administrator role was removed has no account left that could create one. They can be edited.
max_file_bytes?|Largest single file each account in it may send.
null means server.max_body_bytes applies; 0 means no limit here.
int640 <= valuemembers*integerHow many accounts are in it.
What an operator wants before editing. Changing an empty role is free; changing one held by forty accounts is not.
int640 <= valuename*stringWhat an operator types and reads.
permissions*array<string>What it allows, as resource:verb strings.
quota_bytes?|How much storage each account in it may hold.
null means the instance ceiling applies; 0 means no ceiling.
int640 <= valueupdated_at*stringWhen its permissions last changed, RFC 3339.
curl -X POST 'https://example.com/api/v1/admin/roles' \ -H 'Content-Type: application/json' \ -d '{ "name": "string", "permissions": [ "string" ]}'{ "created_at": "string", "description": "string", "id": "string", "is_system": true, "max_file_bytes": 0, "members": 0, "name": "string", "permissions": [ "string" ], "quota_bytes": 0, "updated_at": "string"}