Skip to content
Yagra

The permission catalogue plus, for each role, what it grants.

GET
/api/v1/roles
curl --request GET \
  --url https://example.com/api/v1/roles \
  --header 'Authorization: Bearer <token>'

Only View, unlike the rest of this module: it is the shape of the permission model, not anyone’s account. Derived from Permission::ALL and Role::ALL rather than listed here, so a new permission appears in the matrix without anyone remembering to add it.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The permission catalogue and what each role grants

Media typeapplication/json

The role-vs-privilege matrix.

object
permissions
required
Array<object>

One permission in the role/privilege matrix.

object
description
required
string
key
required
string
label
required
string
roles
required
Array<object>

One role in the matrix: its metadata and the permission keys it grants.

object
builtin
required

Built-in roles are fixed (custom roles are not configurable yet).

boolean
description
required
string
key
required
string
label
required
string
permissions
required

The keys of the permissions this role grants.

Array<string>
Examplegenerated
{
  "permissions": [
    {
      "description": "example",
      "key": "example",
      "label": "example"
    }
  ],
  "roles": [
    {
      "builtin": true,
      "description": "example",
      "key": "example",
      "label": "example",
      "permissions": [
        "example"
      ]
    }
  ]
}

401

Section titled “401”

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

Role lacks read access

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}