How to (re)generate my Jenkins user token

Issue

How can we programmatically generate an API token?
How can we change the user API token (legacy API token)?

Environment

CloudBees CI on modern cloud platforms - operations center
CloudBees CI on modern cloud platforms - managed controller
CloudBees CI on traditional platforms - operations center
xref:latest@release-notes:cloudbees-ci:index.adoc[CloudBees CI on traditional platforms - client controller
Jenkins LTS

Resolution

What is an APIToken?

An API Token is a Jenkins generated code that allow you to use se HTTP BASIC authentication in order to make operations using CLI or REST calls to the Jenkins API.

Where to generate an API token?

If you have an operations center, API tokens need to be generated on the operations center. If you do it on a controller, then the operations center will overwrite or remove the token. If you create an API Token on a controller, you may think that everything is fine because the token does work and is visible in the Jenkins UI, but this will only work as long as you don’t logout from Jenkins.

Using the modern API (from Jenkins version 2.138.1)

Creating a token from the UI

Go to your Jenkins instance and login with the user that you want to generate the API Token for.

Then open the user profile page.

Click on Configure to open the user configuration page.

Locate the Add new Token button.

Given a name to the new token and click on the Generate button.

Retrieve the token. It won’t be displayed again so if you lose it you will have to delete it and recreate it.

Programmatically creating a token

Using Groovy

A Jenkins administrator can create a token for any user from the Groovy Console:

import hudson.model.*
import jenkins.model.*
import jenkins.security.*
import jenkins.security.apitoken.*

// script parameters
def userName = 'admin'
def tokenName = 'kb-token'

def user = User.get(userName, false)
def apiTokenProperty = user.getProperty(ApiTokenProperty.class)
def result = apiTokenProperty.tokenStore.generateNewToken(tokenName)
user.save()

return result.plainValue▼

The return of the script will be the token.

Using the REST API

To create an API token through the REST API, you need to first obtain a crumb token and a session cookie.

This next command will create a CRUMB variable and a cookies.txt file.

CRUMB=$(curl "<jenkinsURL>/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,%22:%22,//crumb)" \
    --cookie-jar cookies.txt \
    --user '<username>')▼

Replace <username> with the user that will generate the API token.

You will be prompted to authenticate with the user you have specified with <username>. Use the user’s password or an existing API token.

The cookies.txt file will contain the session cookie and will have the following format:

# Netscape HTTP Cookie File
# https://curl.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

#HttpOnly_localhost     FALSE   /       FALSE   0       JSESSIONID.REDACTED▼

The CRUMB variable will contain the crumb token and will look like this:

Jenkins-Crumb:REDACTED▼

Now you can create a token using the following command:

curl  '<jenkinsURL>/user/<user>/descriptorByName/jenkins.security.ApiTokenProperty/generateNewToken' \
    --user '<username>' \
    --data 'newTokenName=kb-token' \
    --cookie cookies.txt \
    -H $CRUMB▼

Replace <user> with the user that is recieving the new API token. Replace <username> with the user that is generating the API token. This can be the same user as <user> or can be another user with the Overall/Administrator permission.

You will be prompted to authenticate with the user you have specified with <username>. Use this user’s password or an existing API token.

The response of the call will contain a JSON with the token:

{
  "status": "ok",
  "data": {
    "tokenName": "kb-token",
    "tokenUuid": "30b1644d-e0f0-35e3-ad34-109b93025ec4",
    "tokenValue": "REDACTED"
  }
}▼

With this method, a user with the Overall/Administrator permission can create API tokens for other users only if the Java option -Djenkins.security.ApiTokenProperty.adminCanGenerateNewTokens=true is configured in the instance where the API tokens are generated. Users without the Overall/Administrator permission can only create API tokens for themselves.

Last tested on version CloudBees CI 2.516.1.28665.

Using the legacy API (Jenkins prior to 2.138.1)

Go to your Jenkins instance and login with the user that you want to generate the API Token for.

Then open the user profile page

Click on Configure to open the user configuration page

In order to show the current APIToken click on Show API Token button

To generate a new APIToken click on Change API Tokenbutton