Jenkins Remote Build Trigger - Build Jobs with URL and Token

Jenkins Build Trigger using remote access API is a key element when it comes to automating the Deployment process and implementing the CI/CD pipelines with Jenkins.

In this post, we are going to see how to create a Jenkins Job or Project and configure API token and enable REMOTE API and trigger it from remote.

This RemoteAPI can be used as a Webhook in the Source Control Management Product like Bitbucket, GitHub, Beanstalk etc.

This can be added to the OnPush (or) OnCommit event. So whenever there is a new code commit to the repository the Jenkins Job would be triggered automatically so that you would have the Latest Code Deployed in your application server as soon as you make any changes

Steps to configure Jenkins Remote Build Trigger without any Plugin

This methodology is little complicated as we need to create a Jenkin user along with the token for the build trigger to work. It does not allow anonymous users to initiate a build just by using the Token. While it sounds Secure, It has it cons and this is not developer-friendly.

  1. Create a Build User in Jenkins
  2. Create an Authentication token for the Build User created in the preceding step
  3. Configure Global Security and Project-based Matrix ( If you have Project-based Security)
  4. Create a Job/Project
  5. Map user permissions on the job-based security configuration ( If you have project-based Security)
  6. Create an API token for the job created
  7. Test the Remote API and trigger the build using Chrome
  8. Test the Remote API and trigger the build using CURL
  9. Test the Remote API and trigger the build using Postman


Step1:  Create a Build User in Jenkins

Login to Jenkins as Admin User -> Manage Jenkins -> Manage Users -> Create User

Jenkins Build Trigger

Step2:  Create an Authentication Token for BuildUser

Login to Jenkins as BuildUser -> Click on the user and Configure

In the configuration page, Go to the API Token Section and Add New Token

Enter Name for the Token AuthToken  and click on Generate

Once clicked on the Generate buttion you would be presented with the API token as shown below.

Step3:  Configure Global Security and Project-Based Matrix

Logout from the BuildUser and Log back in as Admin user.

Manage Jenkins -> Configure Global Security -> Authorization -> Click on Add User or Group


Step4:  Create a JOB/Project to test.

Please refer this article on how to create a Maven Job in Jenkins and Build and Deploy a WAR file  to Tomcat.

Jenkins Tomcat Deploy – Deploying Application to Tomcat using Jenkins

Once you have created the Job come back here


Step5:  Configure Job-based Security for the same Project

If you have configured the Job-based project matrix security in Jenkins.

You might have to do this step as well and give necessary permissions for BuildUser to be able to execute the build as shown in the following picture.

Job -> Configure -> Enable Project-based security -> Add user or group -> Add the BuildUser

Once you have added the BuildUser select necassary permissions as shown in the following snapshot.

Stay on the same Page to configure the API token

Step6:  Configure API token

On the same Job Configuration page, Below the Build Triggers section

Select the Trigger builds remotely and Enter some Authentication Token as shown below.

In my case the Authentication Token is SOMESECURITYTOKEN

Jenkins Remote Trigger

as given in the helper text,  the Remote API build trigger URL has to be formed as  JENKINS_URL/job/TomcatMavenApp-Build/build?token=TOKEN_NAME


Step7:  Test the Remote API Build Trigger using the Browser

In my case the Remote Build API URL is http://mwiapp01:8080/job/TomcatMavenApp-Build/build?token=SOMESECURETOKEN

Now you can open a new tab and enter this URL and test the same

You will see the blank page which indicates that the build is executed.

If you go to the other tab where the Jenkins UI tab.

Jenkins Build Trigger

 How it worked in chrome without Username and API token ?

If you have noticed we did not pass any Username or API token/Password while triggering the build but the build went fine.

The reason being, we opened a new tab on the same browser session where Jenkins was already open and the cookies available in the browser session has been automatically read and we have not been asked for a password. If you try in incognito mode. You would see the Login page.

If you try the same URL in incognito browser mode, you would see the login page of Jenkins

Step8: Test the Remote API Build Trigger using CURL

Use the same remote build trigger URL you have used in Step7 and invoke the build using CURL

Here is the CURL command with a Fully Qualified Jenkins Build URL. Refer the preceding Snapshot to understand the various parts of this command.

curl -I -u BuildUser:11aa6524a15c315dff4867eea7b69c9ce2 "http://mwiapp01:8080/job/TomcatMavenApp-Build/build?token=SOMESECURETOKEN"

Here -u represents the user name and password to be passed to invoke the build trigger.

Here HTTP 201  represents a SUCCESS


Step9: Test the Remote API Build Trigger using Postman

In postman, it is very simple and all you have to do is enter the URL and enter the Basic Auth credentials (user, auth token).

Refer the following screenshot for further information

Jenkins Build Trigger


Steps to configure Build Trigger with build token root plugin


In this method we use a plugin named build-token-root it offers an alternate URI pattern which is not subject to the usual job permissions, this URI is accessible to anonymous users as well. Anyone can initiate the build as long as the build token is valid. it supports various URI Patterns like buildWithParameters and buildByToken and polling and accept both GET and POST methods

  1. Install the Build Authorization Token Root Plugin
  2. Edit the Job Configuration and Set Remote Build Trigger Token
  3. Test it.!!

It is that simple with this second approach. You just have to edit the job configuration and create a Token.


Step1: Install the Build Authorization Token Root Plugin

Go to Manage Plugins -> Manage Plugins -> Available tab and search for Build Authorization Token Root plugin and install it.


Step2: Edit the Job Configuration and Set Authentication Token

This is the same task we did on Step6 on the method#1 previously. If you have already done it you can skip it.


Step3: Testing time

There are various types of URLs you can form based on your requirement

Remote trigger the build for Simple Jobs with No Parameters

You can simply invoke them using the following URL structure

Unlike the previous method, this URI looks generic where you can pass the token and the job name as a search query

You can pass any job name and its token to invoke that particular job


Remote trigger the build for Parameterized Jobs

Let us suppose that your job is expecting a String parameter named Branch  and your job name is TestJob Here is the command you should use to invoke the same


How to know if the build is initiated successfully

When you are making a remote request to this URL, there would not be any response message generated except the HTTP status code 201 indicating it is success

So Always look for the HTTP response code to make sure your build is successful or not.

Here is a Snapshot was taken from Postman logs showing the response code and the request and response headers.

jenkins remote build


How to schedule the build (or) Delay the build when triggering remote

Either you are using the first method or the second one with the plugin, both of them accepts a query string named delay where you can define, how long Jenkins should wait before initiating the build

Let us take the same job we have initiated above and add some strategical delay to it by adding a delay=<number of seconds> on the URL query string


After invoking this URL and validating the http 201 response code  If you go to the Jenkins UI, you would be able to see the build in pending state like this

you can look at the message pending--in the quite period this represents that the build has been scheduled

Jenkins Remote build trigger



Hope this article has helped you to understand how Jenkins remote build triggers are working. How to trigger jobs in Jenkins using URL (or) API token.

If you are looking for any further assistance or professional support. you can contact us at [email protected]

Sarav AK

Follow me on Linkedin My Profile
Follow DevopsJunction onFacebook orTwitter
For more practical videos and tutorials. Subscribe to our channel

Buy Me a Coffee at

Signup for Exclusive "Subscriber-only" Content