How to (re)generate my Jenkins user token

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 Master, then the Operation Center will overwrite or remove the token. If you create an APIToken on a Master, 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

You can create a token with the command:

curl '<jenkinsURL>/me/descriptorByName/jenkins.security.ApiTokenProperty/generateNewToken' \
--data 'newTokenName=kb-token' \
--user '<username>:<password>'

The return of the call will contain a json with the token:

{"status":"ok","data":{"tokenName":"kb-token","tokenUuid":"8c42630b-4be5-4f51-b4e9-f17a8ac07521","tokenValue":"112fe6e9b1b94eb1ee58f0ea4f5a1ac7bf"}}

The user running this command should have the Administrator rights.

Using the legacy API (Jenkins prior to 2.138.1)

NOTE: 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

Have more questions?

4 Comments

Please sign in to leave a comment.