Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Managing authorizations by using the REST API

To automate the maintenance of Red Hat Developer Hub permission policies and roles, you can use Developer Hub role-based access control (RBAC) REST API.

You can perform the following actions with the REST API:

  • Retrieve information about:

    • All permission policies
    • Specific permission policies
    • Specific roles
    • Static plugins permission policies

  • Create, update, or delete:

    • Permission policy
    • Role

4.1. Sending requests to the RBAC REST API by using the curl utility

You can send RBAC REST API requests by using the curl utility.

Prerequisites

Procedure

  1. Find your Bearer token to authenticate to the REST API.

    1. In your browser, open the web console Network tab.
    2. In the main screen, reload the Developer Hub Homepage.
    3. In the web console Network tab, search for the query?term= network call.
    4. Save the token in the response JSON for the next steps.

  2. In a terminal, run the curl command and review the response:

    GET or DELETE request

    curl -v \
  -H "Authorization: Bearer <token>" \
  -X <method> "https://<my_developer_hub_url>/<endpoint>" \
    Copy to Clipboard

    POST or PUT request requiring JSON body data

    curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -X POST "https://<my_developer_hub_url>/<endpoint>" \
  -d <body>
    Copy to Clipboard

    <token>
    Enter your saved authorization token.
    <method>

    Enter the HTTP method for your API endpoint.

    • GET: To retrieve specified information from a specified resource endpoint.
    • POST: To create or update a resource.
    • PUT: To update a resource.
    • DELETE: To delete a resource.
    https://<my_developer_hub_url>
    Enter your Developer Hub URL.
    <endpoint>
    Enter the API endpoint to which you want to send a request, such as /api/permission/policies.
    <body>
    Enter the JSON body with data that your API endpoint might need with the HTTP POST or PUT request.

    Example request to create a role

    curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -X POST "https://<my_developer_hub_url>/api/permission/roles" \
  -d '{
      "memberReferences": ["group:default/example"],
      "name": "role:default/test",
      "metadata": { "description": "This is a test role" }
    }'
    Copy to Clipboard

    Example request to update a role

    curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -X PUT "https://<my_developer_hub_url>/api/permission/roles/role/default/test" \
  -d '{
          "oldRole": {
            "memberReferences":  [ "group:default/example" ],
            "name": "role:default/test"
          },
          "newRole": {
            "memberReferences": [ "group:default/example", "user:default/test" ],
            "name": "role:default/test"
          }
        }'
    Copy to Clipboard

    Example request to create a permission policy

    curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -X POST "https://<my_developer_hub_url>/api/permission/policies" \
  -d '[{
      "entityReference":"role:default/test",
      "permission": "catalog-entity",
      "policy": "read", "effect":"allow"
    }]'
    Copy to Clipboard

    Example request to update a permission policy

    curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -X PUT "https://<my_developer_hub_url>/api/permission/policies/role/default/test" \
  -d '{
         "oldPolicy": [
           {
             "permission": "catalog-entity", "policy": "read", "effect": "allow"
           }
         ],
         "newPolicy":
           [
             {
               "permission": "policy-entity", "policy": "read", "effect": "allow"
             }
           ]
       }'
    Copy to Clipboard

    Example request to create a condition

    curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -X POST "https://<my_developer_hub_url>/api/permission/roles/conditions" \
  -d '{
      "result": "CONDITIONAL",
      "roleEntityRef": "role:default/test",
      "pluginId": "catalog",
      "resourceType": "catalog-entity",
      "permissionMapping": ["read"],
      "conditions": {
        "rule": "IS_ENTITY_OWNER",
        "resourceType": "catalog-entity",
        "params": {"claims": ["group:default/janus-authors"]}
      }
    }'
    Copy to Clipboard

    Example request to update a condition

    curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -X PUT "https://<my_developer_hub_url>/api/permission/roles/conditions/1" \
  -d '{
          "result":"CONDITIONAL",
          "roleEntityRef":"role:default/test",
          "pluginId":"catalog",
          "resourceType":"catalog-entity",
          "permissionMapping": ["read",  "update", "delete"],
          "conditions": {
            "rule": "IS_ENTITY_OWNER",
            "resourceType": "catalog-entity",
            "params": {"claims": ["group:default/janus-authors"]}
          }
       }'
    Copy to Clipboard

Verification

  • Review the returned HTTP status code:

    200 OK
    The request was successful.
    201 Created
    The request resulted in a new resource being successfully created.
    204 No Content
    The request was successful, and the response payload has no more content.
    400 Bad Request
    Input error with the request.
    401 Unauthorized
    Lacks valid authentication for the requested resource.
    403 Forbidden
    Refusal to authorize request.
    404 Not Found
    Could not find requested resource.
    409 Conflict
    Request conflict with the current state and the target resource.

4.2. Sending requests to the RBAC REST API by using a REST client

You can send RBAC REST API requests using any REST client.

Prerequisites

Procedure

  1. Find your Bearer token to authenticate to the REST API.

    1. In your browser, open the web console Network tab.
    2. In the main screen, reload the Developer Hub Homepage.
    3. In the web console Network tab, search for the query?term= network call.
    4. Save the token in the response JSON for the next steps.

  2. In your REST client, run a command with the following parameters and review the response:

    Authorization
    Enter your saved authorization token.
    HTTP method

    Enter the HTTP method for your API endpoint.

    • GET: To retrieve specified information from a specified resource endpoint.
    • POST: To create or update a resource.
    • PUT: To update a resource.
    • DELETE: To delete a resource.
    URL
    Enter your Developer Hub URL and API endpoint: https://<my_developer_hub_url>/<endpoint>, such as https://<my_developer_hub_url>/api/permission/policies.
    Body
    Enter the JSON body with data that your API endpoint might need with the HTTP POST request.

4.3. Supported RBAC REST API endpoints

The RBAC REST API provides endpoints for managing roles, permissions, and conditional policies in the Developer Hub and for retrieving information about the roles and policies.

4.3.1. Roles

The RBAC REST API supports the following endpoints for managing roles in the Red Hat Developer Hub.

[GET] /api/permission/roles

Returns all roles in Developer Hub.

Example response (JSON)

[
  {
    "memberReferences": ["user:default/username"],
    "name": "role:default/guests"
  },
  {
    "memberReferences": [
      "group:default/groupname",
      "user:default/username"
    ],
    "name": "role:default/rbac_admin"
  }
]
Copy to Clipboard

[GET] /api/permission/roles/<kind>/<namespace>/<name>

Returns information for a single role in Developer Hub.

Example response (JSON)

[
  {
    "memberReferences": [
      "group:default/groupname",
      "user:default/username"
    ],
    "name": "role:default/rbac_admin"
  }
]
Copy to Clipboard

[POST] /api/permission/roles/<kind>/<namespace>/<name>

Creates a role in Developer Hub.

Table 4.1. Request parameters
NameDescriptionTypePresence

body

The memberReferences, group, namespace, and name the new role to be created.

Request body

Required

Example request body (JSON)

{
  "memberReferences": ["group:default/test"],
  "name": "role:default/test_admin"
}
Copy to Clipboard

Example response

201 Created
Copy to Clipboard

[PUT] /api/permission/roles/<kind>/<namespace>/<name>

Updates memberReferences, kind, namespace, or name for a role in Developer Hub.

Request parameters

The request body contains the oldRole and newRole objects:

NameDescriptionTypePresence

body

The memberReferences, group, namespace, and name the new role to be created.

Request body

Required

Example request body (JSON)

{
  "oldRole": {
    "memberReferences": ["group:default/test"],
    "name": "role:default/test_admin"
  },
  "newRole": {
    "memberReferences": ["group:default/test", "user:default/test2"],
    "name": "role:default/test_admin"
  }
}
Copy to Clipboard

Example response

200 OK
Copy to Clipboard

[DELETE] /api/permission/roles/<kind>/<namespace>/<name>?memberReferences=<VALUE>

Deletes the specified user or group from a role in Developer Hub.

Table 4.2. Request parameters
NameDescriptionTypePresence

kind

Kind of the entity

String

Required

namespace

Namespace of the entity

String

Required

name

Name of the entity

String

Required

memberReferences

Associated group information

String

Required

Example response

204
Copy to Clipboard

[DELETE] /api/permission/roles/<kind>/<namespace>/<name>

Deletes a specified role from Developer Hub.

Table 4.3. Request parameters
NameDescriptionTypePresence

kind

Kind of the entity

String

Required

namespace

Namespace of the entity

String

Required

name

Name of the entity

String

Required

Example response

204
Copy to Clipboard

4.3.2. Permission policies

The RBAC REST API supports the following endpoints for managing permission policies in the Red Hat Developer Hub.

[GET] /api/permission/policies

Returns permission policies list for all users.

Example response (JSON)

[
  {
    "entityReference": "role:default/test",
    "permission": "catalog-entity",
    "policy": "read",
    "effect": "allow",
    "metadata": {
      "source": "csv-file"
    }
  },
  {
    "entityReference": "role:default/test",
    "permission": "catalog.entity.create",
    "policy": "use",
    "effect": "allow",
    "metadata": {
      "source": "csv-file"
    }
  },
]
Copy to Clipboard

[GET] /api/permission/policies/<kind>/<namespace>/<name>

Returns permission policies related to the specified entity reference.

Table 4.4. Request parameters
NameDescriptionTypePresence

kind

Kind of the entity

String

Required

namespace

Namespace of the entity

String

Required

name

Name related to the entity

String

Required

Example response (JSON)

[
  {
    "entityReference": "role:default/test",
    "permission": "catalog-entity",
    "policy": "read",
    "effect": "allow",
    "metadata": {
      "source": "csv-file"
    }
  },
  {
    "entityReference": "role:default/test",
    "permission": "catalog.entity.create",
    "policy": "use",
    "effect": "allow",
    "metadata": {
      "source": "csv-file"
    }
  }
]
Copy to Clipboard

[POST] /api/permission/policies

Creates a permission policy for a specified entity.

Table 4.5. Request parameters
NameDescriptionTypePresence

entityReference

Reference values of an entity including kind, namespace, and name

String

Required

permission

Permission from a specific plugin, resource type, or name

String

Required

policy

Policy action for the permission, such as create, read, update, delete, or use

String

Required

effect

Indication of allowing or not allowing the policy

String

Required

Example request body (JSON)

[
  {
    "entityReference": "role:default/test",
    "permission": "catalog-entity",
    "policy": "read",
    "effect": "allow"
  }
]
Copy to Clipboard

Example response

201 Created
Copy to Clipboard

[PUT] /api/permission/policies/<kind>/<namespace>/<name>

Updates a permission policy for a specified entity.

Request parameters

The request body contains the oldPolicy and newPolicy objects:

NameDescriptionTypePresence

permission

Permission from a specific plugin, resource type, or name

String

Required

policy

Policy action for the permission, such as create, read, update, delete, or use

String

Required

effect

Indication of allowing or not allowing the policy

String

Required

Example request body (JSON)

{
  "oldPolicy": [
    {
      "permission": "catalog-entity",
      "policy": "read",
      "effect": "allow"
    },
    {
      "permission": "catalog.entity.create",
      "policy": "create",
      "effect": "allow"
    }
  ],
  "newPolicy": [
    {
      "permission": "catalog-entity",
      "policy": "read",
      "effect": "deny"
    },
    {
      "permission": "policy-entity",
      "policy": "read",
      "effect": "allow"
    }
  ]
}
Copy to Clipboard

Example response

200
Copy to Clipboard

[DELETE] /api/permission/policies/<kind>/<namespace>/<name>?permission={value1}&policy={value2}&effect={value3}

Deletes a permission policy added to the specified entity.

Table 4.6. Request parameters
NameDescriptionTypePresence

kind

Kind of the entity

String

Required

namespace

Namespace of the entity

String

Required

name

Name related to the entity

String

Required

permission

Permission from a specific plugin, resource type, or name

String

Required

policy

Policy action for the permission, such as create, read, update, delete, or use

String

Required

effect

Indication of allowing or not allowing the policy

String

Required

Example response

204 No Content
Copy to Clipboard

[DELETE] /api/permission/policies/<kind>/<namespace>/<name>

Deletes all permission policies added to the specified entity.

Table 4.7. Request parameters
NameDescriptionTypePresence

kind

Kind of the entity

String

Required

namespace

Namespace of the entity

String

Required

name

Name related to the entity

String

Required

Example response

204 No Content
Copy to Clipboard

[GET] /api/permission/plugins/policies

Returns permission policies for all static plugins.

Example response (JSON)

[
  {
    "pluginId": "catalog",
    "policies": [
      {
        "isResourced": true,
        "permission": "catalog-entity",
        "policy": "read"
      },
      {
        "isResourced": false,
        "permission": "catalog.entity.create",
        "policy": "create"
      },
      {
        "isResourced": true,
        "permission": "catalog-entity",
        "policy": "delete"
      },
      {
        "isResourced": true,
        "permission": "catalog-entity",
        "policy": "update"
      },
      {
        "isResourced": false,
        "permission": "catalog.location.read",
        "policy": "read"
      },
      {
        "isResourced": false,
        "permission": "catalog.location.create",
        "policy": "create"
      },
      {
        "isResourced": false,
        "permission": "catalog.location.delete",
        "policy": "delete"
      }
    ]
  },
  ...
]
Copy to Clipboard

4.3.3. Conditional policies

The RBAC REST API supports the following endpoints for managing conditional policies in the Red Hat Developer Hub.

[GET] /api/permission/plugins/condition-rules

Returns available conditional rule parameter schemas for the available plugins that are enabled in Developer Hub.

Example response (JSON)

[
   {
      "pluginId": "catalog",
      "rules": [
         {
            "name": "HAS_ANNOTATION",
            "description": "Allow entities with the specified annotation",
            "resourceType": "catalog-entity",
            "paramsSchema": {
               "type": "object",
               "properties": {
                  "annotation": {
                     "type": "string",
                     "description": "Name of the annotation to match on"
                  },
                  "value": {
                     "type": "string",
                     "description": "Value of the annotation to match on"
                  }
               },
               "required": [
                  "annotation"
               ],
               "additionalProperties": false,
               "$schema": "http://json-schema.org/draft-07/schema#"
            }
         },
         {
            "name": "HAS_LABEL",
            "description": "Allow entities with the specified label",
            "resourceType": "catalog-entity",
            "paramsSchema": {
               "type": "object",
               "properties": {
                  "label": {
                     "type": "string",
                     "description": "Name of the label to match on"
                  }
               },
               "required": [
                  "label"
               ],
               "additionalProperties": false,
               "$schema": "http://json-schema.org/draft-07/schema#"
            }
         },
         {
            "name": "HAS_METADATA",
            "description": "Allow entities with the specified metadata subfield",
            "resourceType": "catalog-entity",
            "paramsSchema": {
               "type": "object",
               "properties": {
                  "key": {
                     "type": "string",
                     "description": "Property within the entities metadata to match on"
                  },
                  "value": {
                     "type": "string",
                     "description": "Value of the given property to match on"
                  }
               },
               "required": [
                  "key"
               ],
               "additionalProperties": false,
               "$schema": "http://json-schema.org/draft-07/schema#"
            }
         },
         {
            "name": "HAS_SPEC",
            "description": "Allow entities with the specified spec subfield",
            "resourceType": "catalog-entity",
            "paramsSchema": {
               "type": "object",
               "properties": {
                  "key": {
                     "type": "string",
                     "description": "Property within the entities spec to match on"
                  },
                  "value": {
                     "type": "string",
                     "description": "Value of the given property to match on"
                  }
               },
               "required": [
                  "key"
               ],
               "additionalProperties": false,
               "$schema": "http://json-schema.org/draft-07/schema#"
            }
         },
         {
            "name": "IS_ENTITY_KIND",
            "description": "Allow entities matching a specified kind",
            "resourceType": "catalog-entity",
            "paramsSchema": {
               "type": "object",
               "properties": {
                  "kinds": {
                     "type": "array",
                     "items": {
                        "type": "string"
                     },
                     "description": "List of kinds to match at least one of"
                  }
               },
               "required": [
                  "kinds"
               ],
               "additionalProperties": false,
               "$schema": "http://json-schema.org/draft-07/schema#"
            }
         },
         {
            "name": "IS_ENTITY_OWNER",
            "description": "Allow entities owned by a specified claim",
            "resourceType": "catalog-entity",
            "paramsSchema": {
               "type": "object",
               "properties": {
                  "claims": {
                     "type": "array",
                     "items": {
                        "type": "string"
                     },
                     "description": "List of claims to match at least one on within ownedBy"
                  }
               },
               "required": [
                  "claims"
               ],
               "additionalProperties": false,
               "$schema": "http://json-schema.org/draft-07/schema#"
            }
         }
      ]
   }
   ... <another plugin condition parameter schemas>
]
Copy to Clipboard

[GET] /api/permission/roles/conditions/:id

Returns conditions for the specified ID.

Example response (JSON)

{
  "id": 1,
  "result": "CONDITIONAL",
  "roleEntityRef": "role:default/test",
  "pluginId": "catalog",
  "resourceType": "catalog-entity",
  "permissionMapping": ["read"],
  "conditions": {
    "anyOf": [
      {
        "rule": "IS_ENTITY_OWNER",
        "resourceType": "catalog-entity",
        "params": {
          "claims": ["group:default/team-a"]
        }
      },
      {
        "rule": "IS_ENTITY_KIND",
        "resourceType": "catalog-entity",
        "params": {
          "kinds": ["Group"]
        }
      }
    ]
  }
}
Copy to Clipboard

[GET] /api/permission/roles/conditions

Returns list of all conditions for all roles.

Example response (JSON)

[
  {
    "id": 1,
    "result": "CONDITIONAL",
    "roleEntityRef": "role:default/test",
    "pluginId": "catalog",
    "resourceType": "catalog-entity",
    "permissionMapping": ["read"],
    "conditions": {
      "anyOf": [
        {
          "rule": "IS_ENTITY_OWNER",
          "resourceType": "catalog-entity",
          "params": {
            "claims": ["group:default/team-a"]
          }
        },
        {
          "rule": "IS_ENTITY_KIND",
          "resourceType": "catalog-entity",
          "params": {
            "kinds": ["Group"]
          }
        }
      ]
    }
  }
]
Copy to Clipboard

[POST] /api/permission/roles/conditions

Creates a conditional policy for the specified role.

Table 4.8. Request parameters
NameDescriptionTypePresence

result

Always has the value CONDITIONAL

String

Required

roleEntityRef

String entity reference to the RBAC role, such as role:default/dev

String

Required

pluginId

Corresponding plugin ID, such as catalog

String

Required

permissionMapping

Array permission action, such as ['read', 'update', 'delete']

String array

Required

resourceType

Resource type provided by the plugin, such as catalog-entity

String

Required

conditions

Condition JSON with parameters or array parameters joined by criteria

JSON

Required

name

Name of the role

String

Required

metadata.description

The description of the role

String

Optional

Example request body (JSON)

{
  "result": "CONDITIONAL",
  "roleEntityRef": "role:default/test",
  "pluginId": "catalog",
  "resourceType": "catalog-entity",
  "permissionMapping": ["read"],
  "conditions": {
    "rule": "IS_ENTITY_OWNER",
    "resourceType": "catalog-entity",
    "params": {
      "claims": ["group:default/team-a"]
    }
  }
}
Copy to Clipboard

Example response (JSON)

{
  "id": 1
}
Copy to Clipboard

[PUT] /permission/roles/conditions/:id

Updates a condition policy for a specified ID.

Table 4.9. Request parameters
NameDescriptionTypePresence

result

Always has the value CONDITIONAL

String

Required

roleEntityRef

String entity reference to the RBAC role, such as role:default/dev

String

Required

pluginId

Corresponding plugin ID, such as catalog

String

Required

permissionMapping

Array permission action, such as ['read', 'update', 'delete']

String array

Required

resourceType

Resource type provided by the plugin, such as catalog-entity

String

Required

conditions

Condition JSON with parameters or array parameters joined by criteria

JSON

Required

name

Name of the role

String

Required

metadata.description

The description of the role

String

Optional

Example request body (JSON)

{
  "result": "CONDITIONAL",
  "roleEntityRef": "role:default/test",
  "pluginId": "catalog",
  "resourceType": "catalog-entity",
  "permissionMapping": ["read"],
  "conditions": {
    "anyOf": [
      {
        "rule": "IS_ENTITY_OWNER",
        "resourceType": "catalog-entity",
        "params": {
          "claims": ["group:default/team-a"]
        }
      },
      {
        "rule": "IS_ENTITY_KIND",
        "resourceType": "catalog-entity",
        "params": {
          "kinds": ["Group"]
        }
      }
    ]
  }
}
Copy to Clipboard

Example response

200
Copy to Clipboard

[DELETE] /api/permission/roles/conditions/:id

Deletes a conditional policy for the specified ID.

Example response

204
Copy to Clipboard

4.3.4. User statistics

The licensed-users-info-backend plugin exposes various REST API endpoints to retrieve data related to logged-in users.

No additional configuration is required for the licensed-users-info-backend plugin. If the RBAC backend plugin is enabled, then an administrator role must be assigned to access the endpoints, as the endpoints are protected by the policy.entity.read permission.

The base URL for user statistics endpoints is http://SERVER:PORT/api/licensed-users-info, such as http://localhost:7007/api/licensed-users-info.

[GET] /users/quantity

Returns the total number of logged-in users.

Example request

curl -X GET "http://localhost:7007/api/licensed-users-info/users/quantity" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $token"
Copy to Clipboard

Example response

{ "quantity": "2" }
Copy to Clipboard

[GET] /users

Returns a list of logged-in users with their details.

Example request

curl -X GET "http://localhost:7007/api/licensed-users-info/users" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $token"
Copy to Clipboard

Example response

[
  {
    "userEntityRef": "user:default/dev",
    "lastTimeLogin": "Thu, 22 Aug 2024 16:27:41 GMT",
    "displayName": "John Leavy",
    "email": "dev@redhat.com"
  }
]
Copy to Clipboard

[GET] /users

Returns a list of logged-in users in CSV format.

Example request

curl -X GET "http://localhost:7007/api/licensed-users-info/users" \
-H "Content-Type: text/csv" \
-H "Authorization: Bearer $token"
Copy to Clipboard

Example response

userEntityRef,displayName,email,lastTimeLogin
user:default/dev,John Leavy,dev@redhat.com,"Thu, 22 Aug 2024 16:27:41 GMT"
Copy to Clipboard

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat