Filter Hook since 4.4.0

rest_authentication_errors

Filters whether a REST API request should be blocked as unauthenticated

Description

rest_authentication_errors runs after WordPress's own authentication checks (cookie, application passwords) and is the standard hook for adding custom auth schemes or short-circuiting requests with an error.

When it runs

Runs during REST API bootstrap, after core's built-in authentication handlers have already run and set their result.

Signature

apply_filters( 'rest_authentication_errors', WP_Error|null|bool $errors );

Parameters

errors WP_Error|null|bool — WP_Error if already blocked, null if no error yet, true if already authenticated.

Examples

Basic

add_filter( 'rest_authentication_errors', function( $errors ) {
    error_log( 'REST auth check ran.' );
    return $errors;
} );

Log every REST authentication check.

Real case

add_filter( 'rest_authentication_errors', function( $errors ) {
    if ( ! empty( $errors ) ) {
        return $errors; // don't override an existing error
    }
    if ( empty( $_SERVER['HTTP_X_API_KEY'] ) || ! my_api_key_is_valid( $_SERVER['HTTP_X_API_KEY'] ) ) {
        return new WP_Error( 'rest_forbidden', 'Missing or invalid API key.', array( 'status' => 401 ) );
    }
    return $errors;
} );

Require a custom API key header for headless/REST access.

Edge case

add_filter( 'rest_authentication_errors', function( $errors ) {
    if ( is_wp_error( $errors ) ) {
        return $errors; // never clear an existing error
    }
    return $errors;
} );

Always check for and preserve an existing WP_Error before adding your own logic — overwriting it silently reopens a blocked request.

Common Use Cases

Add a custom authentication scheme (API keys, JWT, signed requests)
Restrict the entire REST API to logged-in users only
Log authentication attempts for security monitoring
Enforce IP allowlisting for headless integrations

Common mistakes

Overwriting an existing WP_Error with null or true, which silently un-blocks a request another plugin already rejected
Running expensive checks (like a remote API call) on every single REST request without caching the result

Related hooks

related rest_api_init
related rest_insert_post

FAQ

What does returning null mean versus WP_Error?

null means 'no opinion, defer to other checks'; a WP_Error means 'block this request with this specific error'.

Is this the right hook to build a headless auth layer?

Yes — it's the standard extension point for custom REST authentication schemes like API keys or signed requests.

Source: wp-includes/rest-api.php

Group wizard

One session: this hook, then each related_hooks entry. Walk it and tell us what to change.

rest_authentication_errors → rest_api_init → rest_insert_post

functions.php — rest_authentication_errors

functions.php

<?php
/**
 * Practice: hook into rest_authentication_errors
 */
add_filter( 'rest_authentication_errors', function( $errors ) {
	// Write your callback here. Always return the value.

	return $errors;
} );

Group tour

rest_authentication_errors · Hook 1 of 3 · Step 1 of 6

Meet rest_authentication_errors

Filters whether a REST API request should be blocked as unauthenticated

type filterphase rest-apisince 4.4.0source wp-includes/rest-api.php

apply_filters( 'rest_authentication_errors', WP_Error|null|bool $errors );

add_filter( 'rest_authentication_errors', function( $errors ) {
    error_log( 'REST auth check ran.' );
    return $errors;
} );

PHP rest_authentication_errors · Hook 1 of 3 · Step 1 of 6

Practice the rest_authentication_errors WordPress filter hook in our interactive sandbox — a VS Code-style editor with a step-by-step rest_authentication_errors tutorial, add_filter exercises, and instant feedback. No local WordPress install required.