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:

VariableDescription
JENKINS_URLThe URL of the Jenkins server
JENKINS_USER / JENKINS_PASSWORD_OR_API_TOKENUsername and Password or API token of a jenkins user that has permissions to manage credentials
JENKINS_CRUMBThe 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"
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.