Skip to content

rest-api.adoc

Latest commit

 

History

History
193 lines (149 loc) · 5.34 KB

rest-api.adoc

File metadata and controls

193 lines (149 loc) · 5.34 KB

REST API methods

Table of Contents

The plugin provides REST APIs for modifying the roles. All of these methods require the user invoking them to have the Jenkins.ADMINISTER permission.

API methods for adding a role

addGlobalRole

Adds a global role with no sids assigned to it. Requires POST to ${JENKINS_URL}/folder-auth/addGlobalRole. The request body should specify the role to be added as a JSON object. For example, to add a role with name foo and providing the Item | Delete and the Item | Configure permissions, the request body should look like this:

{
    "name": "foo",
    "permissions": [
        "hudson.model.Item.Delete",
        "hudson.model.Item.Configure"
    ]
}

For example, you can add the role using curl like this:

curl -X POST -H "Content-Type: application/json" -d \
    '{
        "name": "foo",
        "permissions": [
            "hudson.model.Item.Delete",
            "hudson.model.Item.Configure"
        ]
     }' localhost:8080/folder-auth/addGlobalRole

addFolderRole

Adds a folder role with no sids assigned to it. Requires POST to ${JENKINS_URL}/folder-auth/addFolderRole. The request body should specify the role to be added as a JSON object. For example, to add a role with name foo and providing the`Item | Delete` and the Item | Configure permissions on folders bar`and `foo/baz, the request body should look like this:

{
    "name": "foo",
    "permissions": [
        "hudson.model.Item.Delete",
        "hudson.model.Item.Configure"
    ],
    "folderNames": [
        "foo/baz",
        "bar"
    ]
}

addAgentRole

Adds an agent role with no sids assigned to it. Requires POST to ${JENKINS_URL}/folder-auth/addAgentRole. The request body should specify the role to be added as a JSON object. For example, to add a role with the equal to foo and providing the Agent | Configure permissions on agents bar and baz, the request body should look like this:

{
    "name": "foo",
    "permissions": [
        "hudson.model.Computer.Configure"
    ],
    "agentNames": [
        "bar",
        "baz"
    ]
}

API methods for assigning a sid to a role

assignSidToGlobalRole

Assigns a sid to the role identified by its name. Requires POST to ${JENKINS_URL}/folder-auth/assignSidToGlobalRole. The following query parameters are required:

  • roleName: The sid will be assigned to the global role with the name equal to this parameter.

  • sid: The sid to be assigned to the role with the name equal to the value of roleName.

Using curl, for example, a sid "foo" can be assigned to the role "bar"

curl -X POST -d 'roleName=bar&sid=foo' \
    http://localhost:8080/folder-auth/assignSidToGlobalRole

assignSidToFolderRole

Assigns a sid to the role identified by its name. Requires POST to ${JENKINS_URL}/folder-auth/assignSidToFolderRole. The following query parameters are required:

  • roleName: The sid will be assigned to the folder role with the name equal to this parameter.

  • sid: The sid to be assigned to the role with the name equal to the value of roleName.

Using curl, for example, a sid "foo" can be assigned to the role "bar"

curl -X POST -d 'roleName=bar&sid=foo' \
    http://localhost:8080/folder-auth/assignSidToFolderRole

assignSidToAgentRole

Assigns a sid to the role identified by its name. Requires POST to ${JENKINS_URL}/folder-auth/assignSidToAgentRole. The following query parameters are required:

  • roleName: The sid will be assigned to the agent role with the name equal to this parameter.

  • sid: The sid to be assigned to the role with the name equal to the value of roleName.

Using curl, for example, a sid "foo" can be assigned to the role "bar"

curl -X POST -d 'roleName=bar&sid=foo' \
    http://localhost:8080/folder-auth/assignSidToAgentRole

API methods for deleting a role

deleteGlobalRole

Deletes a global role identified by its name. Requires POST to ${JENKINS_URL}/folder-auth/deleteGlobalRole. The query parameter roleName is required.

Using curl, for example, a role with name "foo" can be deleted

curl -X POST -d 'roleName=foo' http://localhost:8080/folder-auth/deleteGlobalRole

deleteFolderRole

Deletes a folder role identified by its name. Requires POST to ${JENKINS_URL}/folder-auth/deleteGlobalRole. The parameter roleName is required.

curl -X POST -d 'roleName=foo' http://localhost:8080/folder-auth/deleteFolderRole

deleteAgentRole

Deletes an agent role identified by its name. Requires POST to ${JENKINS_URL}/folder-auth/deleteGlobalRole. The parameter roleName is required.

curl -X POST -d 'roleName=foo' http://localhost:8080/folder-auth/deleteAgentRole

Logging in to Jenkins

When using cURL to invoke the API, you need to login as a user with the administrator permissions. See the example below for viewing the home page:

curl -X GET -u $USERNAME:$TOKEN http://localhost:8080/

The API token can be obtained by clicking on your logged in user on the top-right of your Jenkins Home page and then clicking the 'Configure' button in the side bar. For more information about authentication, please see https://wiki.jenkins.io/display/JENKINS/Remote+access+API