ProductsDownload Community Edition

Roles

Role-based access control management

get

Returns all roles.

Authorizations
AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Responses
200

Happy response.

application/json
get
/api/v1/roles
GET /api/v1/roles HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "description": "text",
      "id": "text",
      "created_at": "2025-11-15T21:17:17.451Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}
post

Creates a new role.

Authorizations
AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Body

Contains the fields needed to create a role.

namestring · hq-resource-name · min: 1 · max: 63Required

Sets the unique name of the new role. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring · min: 1 · max: 150Optional

Sets the display name of the new role. If not provided, the value of "name" will be used.

descriptionstring · max: 280Optional

Sets the description of the new role.

Responses
post
/api/v1/roles
POST /api/v1/roles HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 168

{
  "name": "text",
  "display_name": "text",
  "description": "text",
  "policy": [
    {
      "effect": "allow",
      "action": "text",
      "resource": "text"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "description": "text",
  "id": "text",
  "created_at": "2025-11-15T21:17:17.451Z",
  "policy": [
    {
      "effect": "allow",
      "action": "text",
      "resource": "text"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
post

Adds a permission statement to an existing Role's policy. No deduplication is done.

Authorizations
AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters
namestringRequired
Body

Describes the effect for an action and resource.

effectstring · enumRequired

Enumerates permission effects.

Possible values:
actionone ofRequired

Is either a single action or a list of actions.

stringOptional
or
string[] · min: 1Optional
resourceone ofRequired

Is either a single string or a list of strings.

stringOptional
or
string[] · min: 1Optional
Responses
200

Happy response.

application/json
post
/api/v1/roles/{name}/policy
POST /api/v1/roles/{name}/policy HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "effect": "allow",
  "action": "text",
  "resource": "text"
}
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "description": "text",
  "id": "text",
  "created_at": "2025-11-15T21:17:17.451Z",
  "policy": [
    {
      "effect": "allow",
      "action": "text",
      "resource": "text"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
get

Returns a specific role.

Authorizations
AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters
namestringRequired
Responses
200

Happy response.

application/json
get
/api/v1/roles/{name}
GET /api/v1/roles/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "description": "text",
  "id": "text",
  "created_at": "2025-11-15T21:17:17.451Z",
  "policy": [
    {
      "effect": "allow",
      "action": "text",
      "resource": "text"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
delete

Deletes a role.

Authorizations
AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters
namestringRequired
Responses
delete
/api/v1/roles/{name}
DELETE /api/v1/roles/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content
patch

Updates a role.

Authorizations
AuthorizationstringRequired

The bearer token can be obtained by creating a ServiceAccount.

Path parameters
namestringRequired
Body

Updates a role. Absent fields are left untouched.

display_namestring · min: 1 · max: 150Optional

Updates the display name of the role.

descriptionstring · max: 280Optional

Updates the description of the role.

Responses
200

Happy response.

application/json
patch
/api/v1/roles/{name}
PATCH /api/v1/roles/{name} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 154

{
  "display_name": "text",
  "description": "text",
  "policy": [
    {
      "effect": "allow",
      "action": "text",
      "resource": "text"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "description": "text",
  "id": "text",
  "created_at": "2025-11-15T21:17:17.451Z",
  "policy": [
    {
      "effect": "allow",
      "action": "text",
      "resource": "text"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
PreviousGroupsNextPermissions

Last updated

Was this helpful?