REST API Security

REST API security

When to use this skill

Use this skill whenever you expose a custom REST endpoint:

• Any register_rest_route() call.
• Endpoints backing a block editor, admin SPA, or front-end fetch.
• Routes that read private data or perform writes/deletes.
• Adding fields via register_rest_field / extending core routes.

The REST API is reachable by anyone who can reach the site. A missing or permissive permission_callback is broken access control — among the most common WordPress vulnerabilities.

Core principles (and why they matter)

1. permission_callback is mandatory and must be real. It is the authorization boundary. __return_true means "anyone, including logged-out users" — never use it for writes, and rarely for reads of non-public data. (Core warns if it's omitted entirely.)
2. Authorize per method and per object. A route may allow GET publicly but require a capability for POST. Object routes (/items/(?P<id>\d+)) should check the user can act on that object.
3. Declare args with sanitize + validate callbacks. The REST framework processes declared inputs, but undeclared params are not automatically rejected or removed. Build write payloads from an explicit field allowlist, never get_params() wholesale.
4. Don't rely on nonces for authorization. The wp_rest nonce mitigates CSRF with cookie authentication; it does not prove origin or replace capability checks.
5. Escape HTML in responses. JSON is not auto-safe if the client injects values into the DOM. Escape/normalize anything that may be rendered as markup.
6. Use specific namespaces/versions (my-plugin/v1) and least-privileged callbacks.
7. Minimize response payloads. Return the fields the client renders — never raw objects, rows, or user records. Authorize both the records and the fields exposed; minimization cannot replace permission checks. Core's ?_fields= parameter lets clients trim further; it complements, not replaces, a small default payload.

Step-by-step implementation

1. Register on rest_api_init with a versioned namespace.
2. Set permission_callback to a function returning true/false/WP_Error, enforcing the right capability (and per-object check via the request args).
3. Define every parameter under args with required, type, sanitize_callback, validate_callback.
4. Use only declared, validated/sanitized params; authorize every target before writing.
5. Before expensive work, enforce abuse controls and return a WP_Error with status 429 on rejection (not wp_send_json_error() inside REST). Transient counters are non-atomic, evictable, best-effort only; strict limits need an atomic shared backend or edge/server enforcement. See ajax-security for trusted proxy/keying caveats.
6. Perform the authorized operation; return only the permitted fields with rest_ensure_response(), or a WP_Error with an HTTP status. Plain JSON text should remain text; escape at an HTML sink or normalize intentional HTML separately.

Supporting references

Common AI mistakes / anti-patterns

Mistake 1 — permission_callback => __return_true on a write

// ❌ Insecure: anyone (even logged out) can write.
register_rest_route( 'my/v1', '/settings', array(
    'methods'             => 'POST',
    'callback'            => 'my_save_settings',
    'permission_callback' => '__return_true',
) );

// ✅ Secure: enforce a capability.
register_rest_route( 'my/v1', '/settings', array(
    'methods'             => 'POST',
    'callback'            => 'my_save_settings',
    'permission_callback' => static function () {
        return current_user_can( 'manage_options' );
    },
) );

Mistake 2 — Omitting permission_callback entirely

// ❌ Insecure/broken: no callback → access control undefined (and a _doing_it_wrong notice).
register_rest_route( 'my/v1', '/data', array(
    'methods'  => 'GET',
    'callback' => 'my_get_data',
) );

// ✅ Secure: explicit callback, even for public reads.
register_rest_route( 'my/v1', '/data', array(
    'methods'             => 'GET',
    'callback'            => 'my_get_data',
    'permission_callback' => '__return_true', // intentional: this data is public
) );

Mistake 3 — Reading params without sanitize/validate

// ❌ Insecure: raw param straight into a query/update.
function my_save_settings( WP_REST_Request $request ) {
    update_option( 'my_color', $request['color'] );
}

// ✅ Secure: declare args; framework sanitizes/validates before callback runs.
register_rest_route( 'my/v1', '/settings', array(
    'methods'             => 'POST',
    'callback'            => 'my_save_settings',
    'permission_callback' => static fn() => current_user_can( 'manage_options' ),
    'args'                => array(
        'color' => array(
            'required'          => true,
            'type'              => 'string',
            'sanitize_callback' => 'sanitize_hex_color',
            'validate_callback' => static function ( $value ) {
                return (bool) sanitize_hex_color( $value );
            },
        ),
    ),
) );
function my_save_settings( WP_REST_Request $request ) {
    update_option( 'my_color', $request['color'] );
    return rest_ensure_response( array( 'saved' => true ) );
}

Mistake 4 — No per-object authorization

// ❌ Insecure: any user with edit_posts can edit ANY post via the endpoint.
'permission_callback' => static fn() => current_user_can( 'edit_posts' ),

// ✅ Secure: check the specific object using the request.
'permission_callback' => static function ( WP_REST_Request $request ) {
    return current_user_can( 'edit_post', absint( $request['id'] ) );
},

Mistake 5 — Returning unescaped HTML that the client renders

// ❌ Risky: stored markup flows to the DOM unescaped client-side.
return array( 'title' => get_post_field( 'post_title', $id ) );

// ✅ Safer: normalize/escape values that may be rendered as HTML.
return rest_ensure_response( array(
    'title' => esc_html( get_post_field( 'post_title', $id ) ),
) );

Mistake 6 — register_rest_field() without a schema or permission check

// ❌ Insecure: writable field with no capability gate or sanitization.
register_rest_field( 'post', 'my_plugin_meta', array(
    'get_callback'    => function ( $object ) {
        return get_post_meta( $object['id'], '_my_plugin_meta', true );
    },
    'update_callback' => function ( $value, $object ) {
        update_post_meta( $object->ID, '_my_plugin_meta', $value );
    },
) );

// ✅ Secure: schema with sanitize/validate + capability check on update.
register_rest_field(
    'post',
    'my_plugin_meta',
    array(
        'get_callback'    => function ( $object ) {
            return get_post_meta( $object['id'], '_my_plugin_meta', true );
        },
        'update_callback' => function ( $value, $object ) {
            if ( ! current_user_can( 'edit_post', $object->ID ) ) {
                return new WP_Error( 'forbidden', __( 'Forbidden.', 'my-plugin' ), array( 'status' => 403 ) );
            }
            update_post_meta( $object->ID, '_my_plugin_meta', sanitize_text_field( $value ) );
            return true;
        },
        'schema'          => array(
            'type'        => 'string',
            'arg_options' => array(
                'sanitize_callback' => 'sanitize_text_field',
            ),
        ),
    )
);

Mistake 7 — Forgetting batch endpoint authentication

WordPress supports /wp-json/batch/v1 requests that invoke multiple routes in one HTTP request. Each route's permission_callback is still enforced, so never rely on the batch entry point being "internal" — every inner route must authorize itself. You can also use the rest_authentication_errors filter to reject authentication globally when needed.

Mistake 8 — Over-exposing response data

// ❌ Over-exposed: full user records — emails, logins, roles — to any subscriber.
$data = array();
foreach ( my_plugin_get_members() as $member ) {
    $data[] = $member; // WP_User: user_email, user_login, roles, all of it.
}
return rest_ensure_response( $data );

// After the permission callback and query have authorized this member set:
// return only the permitted fields the UI needs.
$data = array();
foreach ( my_plugin_get_members() as $member ) {
    $data[] = array(
        'id'   => absint( $member->ID ),
        'name' => $member->display_name, // JSON text; use textContent in the client.
    );
}
return rest_ensure_response( $data );

Deciding what may leave the server at all (emails, IPs, order data) is a privacy question — see user-data-protection-privacy.

Related: see the ajax-security skill for when to use admin-ajax instead of REST and for the rate-limiting pattern, the http-api-ssrf-prevention skill for outbound HTTP calls from a REST callback, and the user-data-protection-privacy skill for personal data in responses.

Correct code examples

A complete route with permission_callback, per-object check, args sanitize/validate, and a WP_Error failure path is in references/secure-rest-endpoint.php.

Checklist

• Every route defines a permission_callback (no implicit/missing one).
• Writes/deletes enforce a capability; __return_true is used only for truly public reads.
• Per-object routes check the user can act on that object (using request args).
• Authorization differs by method where appropriate (read vs write).
• All params declared under args with sanitize_callback + validate_callback.
• Required params marked required => true; types declared.
• HTML in responses is escaped/normalized.
• Errors return WP_Error with an explicit HTTP status.
• Namespace is versioned and plugin-specific (my-plugin/v1).
• Responses contain only the fields the client needs — no raw objects or user records.
• Write payloads allowlist fields explicitly; undeclared REST params are never persisted wholesale.
• Abuse controls run before expensive work; strict quotas do not rely on transient counters.

Official references

• WP_REST_Request::has_valid_params()

• Transients API

• register_rest_route()

• Adding Custom Endpoints — REST API Handbook

• Routes & Endpoints — permission_callback

• Argument schema, sanitize & validate callbacks

• REST API authentication

• register_rest_field()

• OWASP API Security Top 10