Jenkins: "403 No valid crumb was included in the request"
Jenkins answers a POST with HTTP 403 and this message when CSRF protection is on and the request carries no valid crumb. Requests that sign in with an API token are exempt (Jenkins 2.96 and later). For a script, curl or a tool in your IDE, sign in with your user ID and an API token instead of your password, and the crumb is no longer needed.
Where the message comes from
From Jenkins' own code (hudson.security.csrf.CrumbFilter):
- Only POST requests are checked. Reading with GET keeps working, which is why a script can list jobs but fails on Build Now, stop or an input step.
- When the request is signed in with an API token, the check is skipped (JENKINS-22474, in Jenkins 2.96).
- Otherwise, a request without a valid crumb gets
403andNo valid crumb was included in the request. The Jenkins log adds:No valid crumb was included in request for <address> by <user>. Returning 403. - When a crumb is sent but does not match, the log says
Found invalid crumb … If you are calling this URL with a script, please use the API Token instead.
Fix: sign in with an API token
- In Jenkins, open your user page (your name at the top right), then Security, API Token, Add new Token. Copy the token: Jenkins shows it once.
- Use your user ID and the token where the password was. No crumb, no cookie:
curl -X POST -u 'your-user-id:your-api-token' 'https://jenkins.example.com/job/my-job/build'
If you have to use a password
The default crumb issuer builds the crumb from the user and the web session ID, so a crumb only works together with the session cookie it came with. Jenkins' CSRF protection page: ask /crumbIssuer/api for a crumb, note the Set-Cookie header, then send the crumb and the session cookie with every request.
# 1. a crumb, and keep the session cookie
curl -c cookies.txt -u 'your-user-id:your-password' 'https://jenkins.example.com/crumbIssuer/api/json'
# {"crumb":"…","crumbRequestField":"Jenkins-Crumb", …}
# 2. the POST, with the crumb header and the same cookie
curl -b cookies.txt -u 'your-user-id:your-password' -H 'Jenkins-Crumb: …' -X POST 'https://jenkins.example.com/job/my-job/build'
Use the header named in crumbRequestField (Jenkins-Crumb unless your Jenkins changed it). A crumb fetched without keeping the cookie is the usual reason the second call still gets 403.
Turning CSRF protection off
Jenkins has a startup system property for it (hudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION), and strongly recommends leaving protection on. An API token solves the problem without it.
Jenkins builds in IntelliJ IDEA and other JetBrains IDEs
Pipeline Inbox for Jenkins, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, signs in to each Jenkins server with your user ID and an API token, so building, stopping and answering input steps need no crumb. If a server is given a password instead, the plugin asks for a crumb with its session and tries once more. The build list, Pipeline stages, failed tests and console logs are free; build with parameters, rebuild, stop and input steps are Pro (US$1.50 a month, with a 30-day trial).
Jenkins® is a registered trademark of LF Charities Inc.; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by the Jenkins project or JetBrains.