How do I use RBAC REST API?


  • How do I use RBAC REST API


  • CloudBees Jenkins Enterprise
  • CloudBees Jenkins Operations Center


Jenkins provides a Rich set of REST based APIs for most of the functionality, many times these can be used to write scripts or use them from Command line as a quicker way of getting things done and also by bypassing the UI.

Jenkins always provides a link to the REST API at the bottom right of the browser for the objects where the API is provided, this helps as a starting point to explore the API also get the API endpoint to work with. Jenkins has support for XML, JSON and Python API, this article explores the JSON API.

To get started please get the API token. Visit ${JENKINS_URL}/user/<user_id>/configure or ${JENKINS_URL}/me/configure to get the API Token (click Show API Token...)

This article covers the CloudBees RBAC REST API, complete list of Methods are listed in the CloudBees documentation

Format of the REST API Call, this is applicable for most of the Jenkins APIs

From the above diagram, CloudBees documentation calls API as REST API Commands and Method as Command Name


Below is a simple example which creates a new Group (developers), adds Member(s) to the group, creates a new role (developersRole) and grants appropriate Role(s).

  • Create a new Group, developers
curl -X POST '${JENKINS_URL}/groups/createGroup/api/json?name=developers' --user <user>:<API_TOKEN>
  • Add Member dev1 to the Group developers
curl -X POST '${JENKINS_URL}/groups/developers/addMember/api/json?name=dev1' --user <user>:<API_TOKEN>
  • Create a new Role, developersRole
curl -X POST '${JENKINS_URL}/roles/createRole/api/json?name=developersRole' --user <user>:<API_TOKEN>
  • Grant/Add Role for a given group
curl -X POST '${JENKINS_URL}/groups/developers/grantRole/api/json?role=developersRole&offset=0&inherited=true' --user <User>: <API_TOKEN>

In the above call the parameters offset & inherited are important and the documentation says:

  1. offset, int - Propagation level. 0 - current (e.g. folder), 1 - child, 2 - grand-child, other - error
  2. inherited, boolean - true if the role should be granted to child items

More examples :

  • Revoke/Remove Permission for a role
curl -X POST '${JENKINS_URL}/roles/authenticated/revokePermissions/api/json?permissions=hudson.model.Hudson.Administer' --user <User>: <API_TOKEN>

Role name in the above call is authenticated

  • Grant Permissions, grant specific permission for develop_prod Role
curl -X POST '${JENKINS_URL}/roles/develop_prod/grantPermissions/api/json?permissions=hudson.model.Item.Configure,hudson.model.Item.Read,hudson.scm.SCM.Tag,hudson.model.Item.Discover,hudson.model.Hudson.Read,hudson.model.Item.Workspace,hudson.model.View.Read,hudson.model.Item.Delete,hudson.model.Item.Request' --user <User>: <API_TOKEN>
  • Add an existing role to the list of filterable ones
curl -X POST '${JENKINS_URL}/roles/createFilterableRole/api/json?name=developersRole' --user <user>:<API_TOKEN>

The role developersRole used above must exist. createFilterableRole does not create any role.


  • If you have the CSRF enabled, you will have to add in the API call the parameter -H "${CRUB_TOKEN}"
  • Full list of permissions can be found in ${JENKINS_HOME}/nectar-rbac.xml file.
  • Make sure to use a privileged user to try these APIs, check the Column Required permissions from the API Documentation

Acknowledgements to Raghu Reddy at Assurity Consulting, most of the content of this article was provided by him.

Have more questions?


  • 0
    Allan Selvan

    There is no documentation for creating a role but it works. Is it intentionally not there?


  • 0
    Denys Digtiar

    Here are just a few example of how to use the API endpoints which are documented in

    which includes the Role endpoints.

  • 0
    Allan Selvan

    @Denys Thanks much. Really good documentation indeed of the RBAC roles. 

    Is there also documentation of other Jenkins API's for example : for creating a folder in Jenkins. Also I need a API by which I can add global as well as folder domain credentials in Jenkins.

Please sign in to leave a comment.