API token management in Jenkins - Commands & Configuration

Introduction

API tokens let you securely connect to Jenkins without using your password. They help keep your account safe while allowing automated tools to access Jenkins.

When you want to run Jenkins jobs from scripts without typing your password.

When you need to connect Jenkins to other tools like Git or deployment servers securely.

When you want to revoke access without changing your main password.

When you want to track which tool or script is accessing Jenkins.

When you want to avoid sharing your main password with multiple users or tools.

Commands

Check your current Jenkins user identity using the Jenkins CLI to confirm connection.

Terminal

java -jar jenkins-cli.jar -s http://localhost:8080 who-am-i

Expected Output

Authenticated as: admin

Authorities:

  authenticated

  admin

→

-s - Specifies the Jenkins server URL

Use your API token instead of password to authenticate Jenkins CLI commands securely.

Terminal

java -jar jenkins-cli.jar -s http://localhost:8080 -auth admin:your_api_token who-am-i

Expected Output

Authenticated as: admin

Authorities:

  authenticated

  admin

→

-auth - Use API token for authentication in user:token format

Generate a new API token for your Jenkins user using curl command to automate token creation.

Terminal

curl -X POST -u admin:your_password http://localhost:8080/me/descriptorByName/jenkins.security.ApiTokenProperty/generateNewToken -d 'newTokenName=mytoken'

Expected Output

{"status":"ok","data":{"tokenName":"mytoken","tokenValue":"1234567890abcdef1234567890abcdef"}}

Test the new API token by accessing Jenkins API with curl using the token as password.

Terminal

curl -u admin:1234567890abcdef1234567890abcdef http://localhost:8080/api/json

Expected Output

{"assignedLabels":[{}],"mode":"NORMAL","nodeDescription":"the master Jenkins node","nodeName":"","numExecutors":2,"description":null,"jobs":[{"name":"example-job","url":"http://localhost:8080/job/example-job/","color":"blue"}],"overallLoad":{},"primaryView":{"name":"All","url":"http://localhost:8080/"},"quietingDown":false,"slaveAgentPort":50000,"unlabeledLoad":{},"useCrumbs":true,"useSecurity":true,"views":[{"name":"All","url":"http://localhost:8080/"}]}

Key Concept

If you remember nothing else from this pattern, remember: API tokens let you securely automate Jenkins access without sharing your password.

Common Mistakes

Using the main password instead of an API token for automation.

It exposes your password and can cause security risks if the script is leaked.

Always generate and use a dedicated API token for scripts and automation.

Sharing API tokens publicly or in unsecured places.

Anyone with the token can access your Jenkins account with the same permissions.

Keep API tokens secret and revoke them if you suspect they are compromised.

Not testing the API token after creation.

You might have a typo or permission issue that prevents the token from working.

Always test the token by running a simple Jenkins API command before using it in automation.

Summary

Generate API tokens in Jenkins to allow secure automated access without using your password.

Use the API token with Jenkins CLI or curl commands to authenticate safely.

Test your API token after creation to ensure it works before using it in scripts.