Explainers · Explainer
What Is a Nonce in WordPress? A Plain Explanation

Short answer
A WordPress nonce is a short security token that proves a request came from your site, not from a stranger's page. It guards against cross-site request forgery, where a harmful page tricks a logged-in user's browser into acting on your site. A nonce lasts 12 to 24 hours by default and never replaces a permission check.
Key takeaways
- A WordPress nonce is a short token that proves a request came from your site.
- A nonce lasts 12 to 24 hours by default, split into two 12-hour ticks.
- A nonce guards against cross-site request forgery, not against replay attacks.
- A nonce never proves permission, so always check capabilities with current_user_can.
- WordPress builds a nonce from the time tick, action, user ID, and session token.
What is a nonce in WordPress?
A WordPress nonce is a short security token that proves a request came from your site, not from a stranger's page.
Nonce is short for “number used once”. WordPress's nonces handbook says a nonce helps protect URLs and forms from certain types of misuse, malicious or otherwise. In practice, it is a check that the person who clicked a link or sent a form meant to do so.
The name is a little misleading. WordPress nonces are not strictly numbers: they are a hash made of numbers and letters, and they are not used only once. The same nonce works again during its short lifetime, for the same user and the same action.
How long does a WordPress nonce last?
A WordPress nonce lasts between 12 and 24 hours by default, depending on when in its cycle it was made.
The default lifetime is one day, or 86,400 seconds, set by the nonce_life filter. WordPress splits that day into two 12-hour ticks, and it accepts nonces from the current tick and the last tick.
A nonce made at the start of a tick lives for a full 24 hours, while one made at the end of a tick lives just over 12 hours.
This is why wp_verify_nonce() returns two kinds of “yes”. It returns 1 when the nonce was made in the last 12 hours, and 2 when it was made 12 to 24 hours ago.
It returns false when the nonce is invalid or has run out. The function reference spells out all three results.
How does WordPress build a nonce?
WordPress builds a nonce by hashing the time tick, the action name, the user ID, and the session token.
The wp_create_nonce() reference describes it as a token tied to a specific action, user, user session, and window of time. The result is a 10-character token, such as 295a686963 in the handbook example.
Two more facts shape how nonces behave. First, they use the site's NONCE_KEY and NONCE_SALT values from wp-config.php, so each site makes different tokens. Second, nonces are tied to the current user's session, so if a user logs in or out, the nonces on the page stop working.
Guests need care. WordPress gives all logged-out visitors the same user ID, 0, so core makes the same nonce for every guest by default. The nonce_user_logged_out filter lets a plugin swap in a different ID from its own session system.
What attacks does a nonce protect against?
A nonce protects against cross-site request forgery, where a harmful page tricks a logged-in user's browser into acting on your site.
Cross-site request forgery, or CSRF, works like this: a user is logged in to your site, then opens a harmful page. That page makes the user's browser send a request to your site, such as a link that deletes content. The browser sends the login cookie with it, so the request looks real.
MDN's CSRF glossary explains that such an attack works when a site changes state through HTTP requests, checks only cookies to confirm the user, and uses values an attacker can guess. A nonce breaks that pattern, because the attacker cannot guess the token.
The handbook gives a plain example: an admin link such as post.php?post=123&action=trash could be fired by a hidden image on another page. Add a nonce to the link, and the request fails with a “403 Forbidden” response unless the token is right.
OWASP's CSRF cheat sheet gives the same advice for all web apps: add CSRF tokens to every request that changes state, and check them on the server.
What does a nonce not protect against?
A nonce does not prove who the user is, what they may do, or whether the request is safe to repeat.
The handbook is blunt: nonces should never be relied on for authentication, authorization, or access control. Always check permissions with current_user_can(), and always assume nonces can be compromised. A nonce knows nothing about the user's role, so a valid nonce from a Subscriber is still a Subscriber's request.
WordPress has six pre-defined roles, from Super Admin down to Subscriber, and the Subscriber role holds only the read capability, as WordPress.org's roles guide shows. The nonce check and the permission check do two different jobs, and a safe handler runs both.
A nonce also does not stop replay attacks, since the same token works more than once in its lifetime. It is not encryption, and it is not a password. It is a hash that WordPress checks by making it again and comparing the result.
Which functions create and check nonces?
WordPress gives you six main nonce functions: three to create them, and three to check them.
| Function | Job |
|---|---|
wp_create_nonce() | Makes a token for a specific action |
wp_nonce_field() | Adds a hidden nonce field to a form |
wp_nonce_url() | Adds a nonce to a URL |
wp_verify_nonce() | Checks a nonce and returns 1, 2, or false |
check_admin_referer() | Checks a nonce in an admin URL or form, and stops with a 403 error if it fails |
check_ajax_referer() | Checks a nonce in an AJAX request, and stops if it fails |
wp_create_nonce() takes an action string, such as 'trash-post_' . $post->ID, and returns the token. Make the action string as specific as you can, so one token cannot be reused for a different job.
wp_nonce_field() adds two hidden fields to a form by default: one holds the nonce, and one holds the current URL as the referrer. Its default field name is _wpnonce.
wp_nonce_url() adds the same _wpnonce field to a link. Both functions let you set your own action and field name, and the reference warns you to do so, since attackers know the defaults.
For checks, check_admin_referer() looks at the nonce and the referrer, while check_ajax_referer() looks at the nonce only. Both return 1 or 2 on the same 12-hour basis as wp_verify_nonce(), and both stop the request when the check fails.
Where do nonces show up in WordPress?
Nonces show up in admin forms, admin links, AJAX requests, and REST API calls.
Forms get a hidden field from wp_nonce_field(), which proves the form came from your site and not from elsewhere. Admin links get a _wpnonce value in the query string from wp_nonce_url(), such as the trash-post links in the post list.
AJAX requests need the same care. The handbook notes that for AJAX, the nonce often sits in a hidden field that JavaScript reads, and the server checks it with check_ajax_referer(). Our guide to making AJAX requests in WordPress covers the request side in more depth.
The REST API has its own flow, covered in the next section. Wherever a request changes something on the site, a nonce belongs in it.
How does a nonce work with the REST API?
For the REST API, WordPress makes a nonce with the wp_rest action and sends it in the X-WP-Nonce header.
The flow runs like this: JavaScript on the page gets a nonce from wp_create_nonce( 'wp_rest' ), sends it with each request as the X-WP-Nonce header or a _wpnonce value, and WordPress checks it before it runs the request. Core sends a fresh nonce back in the X-WP-Nonce response header.
The check happens in rest_cookie_check_errors(), which calls wp_verify_nonce() with the wp_rest action. A bad nonce gives a rest_cookie_invalid_nonce error and a 403 response. A request with no nonce at all is treated as coming from a logged-out user, with user ID 0.
Our guide to creating a custom REST API endpoint in WordPress shows where this check fits.
How do you check a nonce in code?
Call wp_verify_nonce() with the sent value and the action string, and stop the request when it returns false.
The WordPress Developer Blog shows the pattern with the value cleaned first:
if ( ! wp_verify_nonce( sanitize_text_field( wp_unslash( $_GET['my_custom_nonce_name'] ) ), 'delete-user' ) ) {
return;
}
sanitize_text_field() and wp_unslash() clean the input before the check, following the WordPress coding standards. The action string, 'delete-user' here, must match the one used when the nonce was made, or the check fails.
For admin screens, check_admin_referer() does the same job and stops the request itself with a 403 error. For AJAX, check_ajax_referer() stops the request and returns -1 when the check fails. If you build forms, our guide to sanitizing and escaping data in WordPress covers the cleaning steps in full.
What mistakes should you avoid?
The most common nonce mistakes are vague action strings, missing permission checks, and making nonces too early.
Watch for these:
- Using a broad action string such as
'my-action'for every form. Make each action as specific as you can, such as'trash-post_' . $post->ID. - Trusting a nonce to prove permission. A nonce proves intent, not rights, so always run a
current_user_can()check beside it. - Calling
wp_create_nonce()before theinithook fires. Wait forinit, as the Developer Blog warns. - Leaving the default action and field name in
wp_nonce_field(). Set your own, since attackers know the defaults. - Putting state-changing actions behind plain GET links with no nonce. OWASP warns against using GET requests for actions that change state.
If you are unsure where your site stands, run through our guide to running a WordPress security audit.
For login safety, see how to add two-factor authentication to WordPress.
Frequently asked questions
Is a WordPress nonce the same as a password?
No. A nonce is a short-lived token that proves the request came from your site, while a password proves who the user is. WordPress nonces are not stored secrets and are not checked once only, so they cannot stand in for a login or a permission check.
What does wp_verify_nonce return?
It returns 1 when the nonce was made in the last 12 hours, 2 when it was made 12 to 24 hours ago, and false when it is invalid or has run out. The default lifetime is one day, split into two 12-hour ticks, so the true lifetime runs between 12 and 24 hours.
Do nonces work for logged-out visitors?
Yes, by default. WordPress gives all logged-out visitors the user ID 0, so core makes the same nonce for every guest. The nonce_user_logged_out filter lets a plugin swap in a different ID from its own session system when guests need their own tokens.
Does a valid nonce mean the user has permission?
No. A nonce proves the request came from your site, but it says nothing about what the user may do. Always pair the nonce check with a current_user_can check, so a valid nonce from a low-role user cannot run an admin action.
Why should the nonce action string be specific?
Make the action string as specific as you can, such as trash-post_123 instead of a broad name. A specific action ties the token to one job, so a token made for one form cannot be reused to run a different action.
Sources
- Nonces WordPress Developer Resources
- Understand and use WordPress nonces properly WordPress Developer Blog
- wp_verify_nonce() WordPress Developer Resources
- wp_create_nonce() WordPress Developer Resources
- Cross-Site Request Forgery Prevention Cheat Sheet OWASP
- Cross-site request forgery (CSRF) MDN
- Roles and Capabilities WordPress.org
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


