Environment
-
CloudBees CI (CloudBees Core) on modern cloud platforms - Managed controller
-
CloudBees CI (CloudBees Core) on modern cloud platforms - Operations Center
-
CloudBees CI (CloudBees Core) on traditional platforms - Client controller
-
CloudBees CI (CloudBees Core) on traditional platforms - Operations Center
Resolution
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...
)
Reference: 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
Examples
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 Groupdevelopers
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:
-
offset, int - Propagation level.
0
- current (e.g. folder),1
- child,2
- grand-child,other
- error -
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.
-
List Group details using tree
curl -g -X GET '${JENKINS_URL}/groups/api/json?tree=groups[name,description,roles,roleAssignments,members,url]' --user <user>:<API_TOKEN>
NOTE:
-
If you have the CSRF enabled, you will have to add in the API call the parameter
-H "${CRUB_TOKEN}"
. From Jenkins 2.96 onward, you can use an API token and avoid using a crumb / CSRF 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.