def create(body = nil, timeout: nil, **fields)def create: (
?(role_create | Hash[Symbol | String, untyped])? body,
?timeout: seconds?,
**untyped
) -> role_resourceCreates a custom role from a full permission list. Take the strings from list_permissions, because anything outside that catalogue is rejected with 400 request.body_invalid.
Two separate ceilings apply to permissions:. Permissions flagged assignableToCustomRoles: false, today workspace:delete and billing:manage, can never be held by a custom role and fail validation for everyone. Beyond that you can only grant what you already hold: the request is checked against the effective permissions of the user who owns the API key, and anything past that fails with 403 auth.permission_denied naming the offending strings in message. An admin therefore cannot mint a role stronger than admin.
Names are trimmed and must be unique within the workspace case insensitively, so Deploy bot collides with deploy bot and returns 409 role.name_conflict. A workspace holds at most 25 custom roles, and the cap is checked before the name, so a full workspace fails with 409 role.limit_reached even when the name was also taken.
Example
require "envless/sdk"
catalogue = Envless.roles.list_permissions
candidates = %i[variables versions].flat_map do |resource|
catalogue[:byResource].fetch(resource, [])
end
readable = candidates.select { |name| name.end_with?(":read") }
role = Envless.roles.create(
name: "Deploy bot",
description: "Read only access for CI",
permissions: readable
)
puts "#{role[:id]} #{role[:permissions]}"Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
body | role_create | No | The fields below as one Hash, with Symbol or String keys, in place of the keywords. |
name: | String | Yes | Display name for the role, trimmed and unique within the workspace. |
permissions: | Array[String] | Yes | Complete list of permission strings from the catalogue, with no merge or inheritance applied. |
description: | String | nil | No | Optional free text shown next to the role. |
timeout: | Integer | Float | Rational | No | Seconds each attempt of this call may take, redirects and the response body included, before it raises Envless::NetworkError with timeout? set. Overrides the client's timeout for this call, and 0 turns the limit off. |
Returns
role_resource for the new role, with isSystem false and systemKey nil.
Worth knowing
- System roles do not count against the 25 role cap, only custom ones do.
- Creating a role emits the
role.createdwebhook event with the permission list in the payload. - Use
catalogue[:systemRoles][:admin]as a template when you want a slightly reduced admin, then remove what the role should not have.
Required scopes
roles:write
Underlying endpoint
POST /roles
Request and response schema, every error code, and a live playground.
In TypeScript
envless.roles.create()
The same method in @goenvless/sdk, with the same request, retries and errors.