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.

Practice

1. What is the main purpose of an API token in Jenkins?

easy

A. To allow secure access to Jenkins without using your password

B. To reset your Jenkins user password automatically

C. To create new Jenkins user accounts

D. To monitor Jenkins server performance

Solution

1. Step 1: Understand API token function

   An API token acts like a password substitute for accessing Jenkins securely.

2. Step 2: Compare options

   Only To allow secure access to Jenkins without using your password correctly describes the token's purpose; others describe unrelated functions.

3. Final Answer:

   To allow secure access to Jenkins without using your password -> Option A

4. Quick Check:

   API token = secure password substitute [OK]

Hint: API tokens replace passwords for safe Jenkins access [OK]

Common Mistakes:

• Thinking tokens reset passwords
• Confusing tokens with user creation
• Assuming tokens monitor performance

2. Which Jenkins menu path lets you create a new API token?

easy

A. Manage Jenkins > Configure System

B. Dashboard > New Item

C. User Profile > Configure > API Token

D. Manage Plugins > Available

Solution

1. Step 1: Locate API token creation

   API tokens are created in the user's own profile settings, not global or plugin menus.

2. Step 2: Match correct menu path

   Only User Profile > Configure > API Token correctly points to User Profile > Configure > API Token.

3. Final Answer:

   User Profile > Configure > API Token -> Option C

4. Quick Check:

   API tokens created in user profile [OK]

Hint: API tokens are in your user profile settings [OK]

Common Mistakes:

• Looking under Manage Jenkins instead of user profile
• Confusing plugin menus with token creation
• Trying to create tokens from dashboard

3. What will happen if you use an invalid API token in a Jenkins REST API call?

medium

A. The API call succeeds but with limited permissions

B. The API call fails with an authentication error

C. The API call triggers a password reset

D. The API call is queued for later processing

Solution

1. Step 1: Understand token validation

   Jenkins checks API tokens for validity before allowing access.

2. Step 2: Identify failure behavior

   Invalid tokens cause authentication failure, so the call is rejected.

3. Final Answer:

   The API call fails with an authentication error -> Option B

4. Quick Check:

   Invalid token = authentication error [OK]

Hint: Invalid tokens cause authentication errors [OK]

Common Mistakes:

• Assuming calls succeed with limited access
• Thinking invalid tokens reset passwords
• Believing calls queue instead of failing

4. You created an API token but Jenkins shows 'Invalid token' error when using it. What is the most likely cause?

medium

A. You copied the token incorrectly or partially

B. You used the token in the Jenkins UI instead of API calls

C. You created the token in the wrong Jenkins instance

D. You forgot to restart Jenkins after creating the token

Solution

1. Step 1: Check token usage errors

   Common error is copying the token incorrectly, causing invalid token errors.

2. Step 2: Evaluate other options

   Tokens work immediately without restart; UI usage is different; wrong instance is less common.

3. Final Answer:

   You copied the token incorrectly or partially -> Option A

4. Quick Check:

   Copy error = invalid token [OK]

Hint: Always copy API tokens fully and exactly [OK]

Common Mistakes:

• Restarting Jenkins unnecessarily
• Using tokens in UI login fields
• Ignoring token instance mismatch

5. You want to revoke an old API token without affecting other tokens. How do you do this safely in Jenkins?

hard

A. Disable your Jenkins user account temporarily

B. Change your Jenkins user password to invalidate all tokens

C. Restart Jenkins to clear all active tokens

D. Delete the specific token from your user profile's API token list

Solution

1. Step 1: Understand token revocation

   Jenkins allows deleting individual API tokens from your user profile without affecting others.

2. Step 2: Compare other methods

   Changing password invalidates all tokens; restarting Jenkins or disabling account are not selective.

3. Final Answer:

   Delete the specific token from your user profile's API token list -> Option D

4. Quick Check:

   Delete token individually to revoke safely [OK]

Hint: Revoke tokens individually via user profile [OK]

Common Mistakes:

• Changing password to revoke one token
• Restarting Jenkins unnecessarily
• Disabling user instead of token