How to manage Credentials via the REST API

Issue

I want to get / update credentials using the REST API

Environment

Resolution

For the complete documentation of Credentials plugin REST API, refer to REST API section of the User Guide of the Credentials plugin.

Examples

In those examples:

Jenkins has a folder top-folder at root level
Jenkins has a folder sub-folder under the top-folder

This article provides examples about how to create, get, update and delete a folder credential of ID my-credentials-example-id in the folder sub-folder.

It uses the following variables:

Variable Description

Variable	Description
`JENKINS_URL`	The URL of the Jenkins server
`JENKINS_USER` / `API_TOKEN`	Username and Password or API token of a jenkins user that has permissions to manage credentials
`JENKINS_CRUMB`	The crumb issued by Jenkins (see CSRF Protection Explained)

JENKINS_URL

The URL of the Jenkins server

JENKINS_USER / API_TOKEN

Username and Password or API token of a jenkins user that has permissions to manage credentials

JENKINS_CRUMB

The crumb issued by Jenkins (see CSRF Protection Explained)

Create Credentials

According to the documentation, a POST request must be sent to $JENKINS_URL/<path to context>/credentials/store/<store id>/domain/<domain name>/createCredentials with the credentials XML configuration as body.

1) Create the credentials.xml content:

cat > credential.xml <<EOF
<com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl>
  <scope>GLOBAL</scope>
  <id>my-credentials-example-id</id>
  <description>This is an example from REST API</description>
  <username>admin</username>
  <password>
    <secret-redacted/>
  </password>
</com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl>
EOF

2) Create the credentials in Jenkins, in the folder top-folder/sub-folder:

curl -X POST \
    -u $JENKINS_USER:$API_TOKEN \
    -H "Jenkins-Crumb:${JENKINS_CRUMB}" \
    -H 'content-type:application/xml' \
    -d @credential.xml \
    "$JENKINS_URL/job/top-folder/job/sub-folder/credentials/store/folder/domain/_/createCredentials"

Get Credentials

According to the documentation, a GET request must be sent to $JENKINS_URL/<path to context>/credentials/store/<store id>/domain/<domain name>/credential/<credentials id>/config.xml.

curl -X GET \
    -u $JENKINS_USER:$API_TOKEN \
    -H "Jenkins-Crumb:${JENKINS_CRUMB}" \
    "$JENKINS_URL/job/top-folder/job/sub-folder/credentials/store/folder/domain/_/credential/my-credentials-example-id/config.xml"

This output the credentials definition in an XML content. The secrets are always redacted:

<com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl plugin="credentials@2.1.19">
  <id>my-credentials-example-id</id>
  <description>This is an example from REST API</description>
  <username>admin</username>
  <password>
    <secret-redacted/>
  </password>
</com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl>

Update Credentials

According to the documentation, a POST request must be sent to $JENKINS_URL/<path to context>/credentials/store/<store id>/domain/<domain name>/credential/<credentials id>/config.xml with the credentials XML configuration as body. POST to $JENKINS_URL/<path to context>/credentials/store/<store id>/domain/<domain name>/credential/<credentials id>/config.xml

1) Update the content of the credentials XML file:

cat > updatedCredential.xml <<EOF
<com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl>
  <scope>GLOBAL</scope>
  <id>my-credentials-example-id</id>
  <description>This is an example from REST API (updated)</description>
  <username>admin</username>
  <password>secret-redacted</password>
</com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl>
EOF

2) Update the existing credentials:

curl -X POST \
    -u $JENKINS_USER:$API_TOKEN \
    -H "Jenkins-Crumb:${JENKINS_CRUMB}" \
    -H 'content-type:application/xml' \
    -d @updatedCredential.xml \
    "$JENKINS_URL/job/top-folder/job/sub-folder/credentials/store/folder/domain/_/credential/my-credentials-example-id/config.xml"

Delete Credentials

According to the documentation, a DELETE request must be sent to $JENKINS_URL/<path to context>/credentials/store/<store id>/domain/<domain name>/credential/<credentials id>/config.xml.

curl -X DELETE \
    -u $JENKINS_USER:$API_TOKEN \
    -H "Jenkins-Crumb:${JENKINS_CRUMB}" \
    "$JENKINS_URL/job/top-folder/job/sub-folder/credentials/store/folder/domain/_/credential/my-credentials-example-id/config.xml"

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.