Issue

• I want to get / update credentials using the REST API

Environment

• CloudBees Core on modern cloud platforms - Managed Master
• CloudBees Core on modern cloud platforms - Operations Center
• CloudBees Core on traditional platforms - Client Master
• CloudBees Core on traditional platforms - Operations Center
• CloudBees Jenkins Distribution
• CloudBees Jenkins Enterprise - Managed Master
• CloudBees Jenkins Enterprise - Operations Center
• CloudBees Jenkins Platform - Client Master
• CloudBees Jenkins Platform - Operations Center
• Jenkins LTS
• Credentials Plugin

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
JENKINS_URL	The URL of the Jenkins server
JENKINS_USER / JENKINS_PASSWORD_OR_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:$JENKINS_PASSWORD_OR_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:$JENKINS_PASSWORD_OR_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>newsupersecret</password>
</com.cloudbees.plugins.credentials.impl.UsernamePasswordCredentialsImpl>
EOF

2) Update the existing credentials:

curl -X POST \
    -u $JENKINS_USER:$JENKINS_PASSWORD_OR_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:$JENKINS_PASSWORD_OR_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"