If you’ve written a WordPress plugin, you’ve almost certainly used a nonce, or been told off by a code review or a security scanner for not using one. WordPress nonces appear in forms, admin links, AJAX requests and REST API calls. They’re one of the most important security tools available to plugin developers and, judging by the vulnerability reports published every week, one of the most frequently misused.
The confusion starts with the name. In cryptography, a nonce is a “number used once”. WordPress nonces aren’t used only once; they’re valid for a period of time and can be reused within it. They’re also often mistaken for authentication or authorisation, which they are not. This article explains what nonces actually protect against, how to use them correctly in different situations and the mistakes that lead to real vulnerabilities.
The problem nonces solve: CSRF
Cross-site request forgery, or CSRF, is an attack where a malicious website tricks a logged-in user’s browser into making a request to your site. The browser automatically includes the user’s cookies, so your site sees a request from a legitimately logged-in administrator.
Imagine a plugin with an admin link that deletes a record:
If the plugin checks only that the current user is an administrator, an attacker could put that URL in an image tag on a page they control. When a logged-in administrator visits the attacker’s page, their browser requests the URL, and the record is deleted without them ever clicking anything.
A nonce fixes this. The real link includes a token that only your site can generate for that user and action. The attacker’s page can’t know the token, so its forged request fails verification.
What a WordPress nonce actually is
A WordPress nonce is a hash generated from:
- An action string you provide, such as “acme_delete_record_15”
- The current user’s ID
- The user’s session token
- A time tick, which changes every 12 hours
By default, a nonce is valid for between 12 and 24 hours, depending on where in the tick it was created. Within that window, it can be used multiple times. That’s why the “used once” name is misleading.
Because the nonce depends on the user and their session, a nonce generated for one user is useless to another. Because it depends on the action string, a nonce for deleting record 15 can’t be used to delete record 16, provided you make the action specific.
What nonces don’t do
This is the most important part. A nonce proves that a request was intentionally made from a page your site generated for this user. It does not prove:
- That the user is allowed to perform the action
- That the user is logged in, in all contexts
- That the input data is valid or safe
You must still check capabilities with current_user_can and sanitise and validate input. Many vulnerabilities reported in plugins come from code that verifies a nonce but skips the capability check, letting any logged-in subscriber perform administrator actions, because subscribers can obtain valid nonces from pages they can access.
The correct pattern always has three parts:
- Verify the nonce.
- Check the user’s capability for this specific action.
- Sanitise and validate the input.
Using nonces in forms
In a form, output a nonce field with wp_nonce_field:
When processing the form:
In admin screens, check_admin_referer is a convenient shortcut that verifies the nonce and stops execution on failure:
If you use the Settings API, nonces are handled for you by settings_fields and options.php.
Using nonces in links
For actions triggered by links, use wp_nonce_url:
And verify when handling the request:
Note that wp_nonce_url returns an HTML-escaped URL, with ampersands encoded as &. That’s correct for printing in an href attribute, but wrong if you use the URL in a redirect or pass it to JavaScript. For those cases, build the URL with add_query_arg and wp_create_nonce instead, so it contains raw ampersands. This is a surprisingly common source of “the link doesn’t work” bugs.
Make action strings specific. Including the record ID in the action means a nonce for one record can’t be reused for another.
Using nonces with admin-ajax.php
For AJAX requests through admin-ajax.php, pass a nonce to your JavaScript and send it with each request:
In the handler:
Be careful with wp_ajax_nopriv_ handlers, which run for logged-out visitors. All logged-out visitors share user ID zero, so nonces offer much weaker protection there. Treat nopriv endpoints as public, and protect them with validation, rate limiting and, where appropriate, bot protection.
Using nonces with the REST API
The REST API uses nonces differently. For requests from your own site’s JavaScript using cookie authentication, WordPress expects a nonce with the action wp_rest, sent in the X-WP-Nonce header:
Without a valid wp_rest nonce, cookie-authenticated requests are treated as unauthenticated. If you use @wordpress/api-fetch, it handles this for you.
Your endpoints must still define a permission_callback that checks capabilities:
Never use __return_true as the permission callback for endpoints that change data.
Nonces and caching
Nonces are tied to users and time. If a page containing a nonce is cached and served to other visitors, they receive a nonce that isn’t valid for them, and forms or AJAX features fail. This commonly affects front-end forms on cached pages.
Solutions include excluding those pages from caching, loading the nonce via a separate uncached AJAX request after page load, or keeping cache lifetimes shorter than the nonce lifetime for logged-out visitors, combined with other protections for public forms.
Common mistakes
From reviewing plugins and vulnerability reports, the same mistakes come up again and again:
- Verifying a nonce but not checking capabilities
- Checking capabilities but not verifying a nonce for state-changing requests
- Using the same generic action string for every operation
- Using wp_verify_nonce without checking its return value
- Verifying a nonce only when it’s present, so requests without one skip the check entirely
- Treating nopriv AJAX nonces as meaningful protection
- Using escaped URLs from wp_nonce_url in redirects or JavaScript
Avoid those, and WordPress nonces become a reliable part of your plugin’s security rather than a box ticked for code review.
Testing your nonce handling
It’s worth testing nonce checks deliberately rather than assuming they work. A few simple tests catch most problems:
- Submit the form or call the endpoint without the nonce parameter at all. It should fail.
- Submit it with a nonce for a different action. It should fail.
- Log in as a lower-privileged user, such as a subscriber, and try the request with a valid nonce they can obtain. It should still fail because of the capability check.
- Wait until the nonce has expired, or adjust nonce_life on a test site, and confirm that expired nonces are rejected with a helpful message.
Automated tests can cover these cases too. With PHPUnit and the WordPress test suite, you can create users with different roles, generate nonces and assert that your handlers reject invalid requests. Tests like these prevent regressions when someone refactors the code later.
Helpful error messages
When a nonce check fails for a genuine user, usually because a page was left open for more than a day, the default “The link you followed has expired” message is confusing. Where possible, give a clearer explanation and a way to retry, such as “This page has been open for a while. Please reload it and try again.” For AJAX features, detect the failure in JavaScript and prompt the user to refresh, rather than leaving a button that silently does nothing.
Where nonces fit in the bigger picture
Nonces are one layer of request security. Combined with capability checks, input sanitisation, output escaping and prepared database queries, they form the core of secure WordPress development. Leave any one out and the others can’t fully compensate. Coding standards tools like PHPCS with the WordPress ruleset flag missing nonce verification automatically, which is a useful safety net while you build the habit.
A short checklist for every handler
Before shipping any code that changes data in response to a request, run through three questions. Does it verify a nonce with a specific action string, and fail when the nonce is missing? Does it check that the current user has the exact capability this action requires, not just that they are logged in? Does it sanitise and validate every piece of input before using it? If all three answers are yes, the handler is protected against the most common classes of request-based vulnerabilities found in WordPress plugins.
Frequently asked questions
How long is a WordPress nonce valid?
Between 12 and 24 hours by default. The lifetime can be changed with the nonce_life filter.
Are nonces required for GET requests?
Only for GET requests that change something, such as deleting or approving items. Read-only requests don’t need them.
Can I use one nonce for multiple actions?
Technically yes, but it’s weaker. Specific action strings limit what a leaked or reused nonce can do.
Do nonces protect against bots?
No. Nonces protect logged-in users from forged requests. Bots that load your page can obtain nonces for logged-out users, so use other protections for public forms.




