How to (re)generate my Jenkins user token

Article ID:115003090592
3 minute readKnowledge base

Issue

  • How can we get a user APIToken?

  • How can we programmatically generate a APIToken?

  • How can we change the user APIToken (legacy APIToken)?

  • If I create a new APIToken and then log out, the APIToken disappears

Environment

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 APIToken?

If you have an Operation Center, APITokens need to be generated on the Operation Center. If you do it on a controller, then the Operation Center will overwrite or remove the token. If you create an APIToken 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 APIToken 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

As a Jenkins administrator, you 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 RestAPI

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>')
▼

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.974c6e10     node01atelbjgy45rs16spc4gkpz8sk3.node0
▼

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

Jenkins-Crumb:45395f500356547dbb37bd45e9f795b18a0866c218c17995a253898c27b3cde0
▼

Now you can create a token using the following command:

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

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": "258edad6xxxxxxxxxxxc568e2700f6c6"
  }
}
▼

Using the legacy API (Jenkins prior to 2.138.1)

While the legacy Token API is still available in latest Jenkins versions, it is strongly suggested to use the modern API when using a recent Jenkins version.

  • Go to your Jenkins instance and login with the user that you want to generate the APIToken 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