API Key Authentication for WordPress REST API

This article focuses strictly on server-to-server and sync use cases. No frontend JavaScript, no theoretical fluff, only patterns that actually make sense in production.

When API Key authentication is the right choice

API Key authentication works best when:

• The REST API is used internally or between trusted websites
• The API is called by cron jobs, background workers, or sync services
• You control both the client and the server
• User-level authentication is not required

If you need per-user permissions or a public developer API, API keys are not the right tool.

Critical rule: never send API keys via URLs

A very common mistake is sending API keys through query parameters:

/wp-json/myapi/v1/data?api_key=SECRET

This is dangerous. URLs can be logged, cached, shared, or exposed by proxies and CDNs. With API keys, URLs must always stay clean.

The correct approach is to send API keys via HTTP headers.

Recommended header format

X-My-App-Key: your-secret-api-key

Custom headers are explicit, secure, and fully supported by the WordPress REST API.

Implementing API Key authentication in WordPress

The correct place to validate API keys is the permission_callback when registering REST routes. This keeps authentication logic completely separate from business logic.

register_rest_route('myapi/v1', '/data', [
    'methods'             => 'GET',
    'callback'            => 'myapi_get_data',
    'permission_callback' => 'myapi_check_api_key',
]);

Validating the API key from request headers

function myapi_check_api_key( $request ) {
    // Get header the proper WordPress REST API way
    $api_key = $request->get_header( 'X-My-App-Key' );

    // Use hash_equals to prevent timing attacks
    if ( empty( $api_key ) || ! hash_equals( 'YOUR_SECRET_KEY', $api_key ) ) {
        return new WP_Error(
            'invalid_api_key',
            'Invalid or missing API key',
            [ 'status' => 401 ]
        );
    }

    return true;
}

This ensures unauthorized requests are blocked immediately, before any application logic is executed.

Example of a protected REST API endpoint

function myapi_get_data($request) {
    return [
        'success' => true,
        'data'    => 'Protected content',
    ];
}

Calling a protected REST API from PHP (server-to-server)

This is the most common API Key use case: one WordPress site or backend service calling another to synchronize data.

$url = 'https://example.com/wp-json/myapi/v1/data';

$response = wp_remote_get($url, [
    'timeout' => 30,
    'headers' => [
        'X-My-App-Key' => 'YOUR_SECRET_KEY',
    ],
]);

if (is_wp_error($response)) {
    // Handle request error
}

$body = wp_remote_retrieve_body($response);
$data = json_decode($body, true);

In this setup, the API key never leaves the server environment, which is exactly how it should be used.

Common mistakes when using API keys

• Sending API keys via query parameters
• Comparing keys with === instead of hash_equals()
• Mixing authentication logic into the API callback
• Using API keys for public APIs

When API keys are not enough

You should consider stronger authentication methods if:

• You need user-level access control
• You are building a public API for third parties
• You need token expiration and revocation

In those cases, OAuth or JWT-based authentication is a better fit.

Conclusion

API Key authentication is a highly effective solution for WordPress REST APIs when used for the right purpose: data synchronization and server-to-server communication. By sending keys through headers, validating them in permission_callback, and keeping secrets strictly on the backend, you get a clean, secure, and maintainable API design.

No shortcuts, no overengineering — just the right tool for the job.