Xác thực API Key cho WordPress REST API

Bài viết này tập trung hoàn toàn vào API Key cho mục đích sync và server-to-server, không lan man lý thuyết và không dùng JavaScript frontend.

Khi nào API Key là lựa chọn đúng?

API Key phù hợp khi:

• REST API chỉ dùng cho nội bộ hoặc giữa các website do bạn kiểm soát
• Dùng để sync dữ liệu, cron job, background task
• Không cần xác thực theo user
• Muốn giải pháp đơn giản, dễ debug, dễ bảo trì

Nếu bạn cần phân quyền theo người dùng hoặc public API cho bên thứ ba, API Key không phải công cụ phù hợp.

Nguyên tắc bắt buộc: không truyền API Key qua URL

Một sai lầm rất phổ biến là truyền API Key qua query string:

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

Cách này cực kỳ nguy hiểm vì URL có thể bị log, cache, chia sẻ hoặc lộ qua CDN. Với API Key, URL phải luôn sạch.

Cách đúng là truyền API Key qua HTTP header.

Header khuyến nghị

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

Custom header rõ ràng, an toàn và được WordPress REST API hỗ trợ đầy đủ.

Triển khai xác thực API Key trong WordPress

Nơi đúng để kiểm tra API Key là permission_callback khi đăng ký REST route. Điều này giúp tách biệt hoàn toàn phần xác thực và phần xử lý dữ liệu.

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

Kiểm tra API Key từ header request

function myapi_check_api_key( $request ) {
    // Lấy header theo cách chuẩn của WP REST API
    $api_key = $request->get_header( 'X-My-App-Key' );

    // Dùng hash_equals để tránh timing attack
    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;
}

Cách này đảm bảo request không hợp lệ bị chặn ngay từ đầu, trước khi chạm vào logic xử lý chính.

Ví dụ REST API được bảo vệ

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

Gọi REST API đã bảo vệ bằng PHP (site-to-site, sync)

Đây là cách sử dụng API Key phổ biến nhất: một website hoặc service khác gọi API để sync dữ liệu.

$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);

API Key lúc này nằm hoàn toàn ở server, không lộ ra frontend, đúng bản chất bảo mật.

Các lỗi thường gặp khi dùng API Key

• Truyền API Key qua query parameter
• So sánh key bằng === thay vì hash_equals()
• Nhét logic xác thực vào callback xử lý dữ liệu
• Dùng API Key cho các API public

Khi nào không nên dùng API Key?

Bạn nên cân nhắc giải pháp khác nếu:

• Cần phân quyền chi tiết theo người dùng
• Xây dựng public API cho bên thứ ba
• Cần token có thời hạn và khả năng revoke

Trong những trường hợp này, OAuth hoặc JWT sẽ phù hợp hơn.

Kết luận

API Key là giải pháp xác thực rất thực tế cho WordPress REST API khi dùng đúng mục đích: sync dữ liệu và giao tiếp server-to-server. Truyền key qua header, kiểm tra trong permission_callback, và giữ key ở backend sẽ giúp bạn có một hệ thống gọn, an toàn và dễ mở rộng.

Không màu mè, không thừa thãi – đúng tinh thần làm API cho sync.