Using WordPress ‘rest_authorization_required_code()’ PHP function

The rest_authorization_required_code WordPress PHP function returns a contextual HTTP error code for authorization failure.

Usage

$error_code = rest_authorization_required_code();

Parameters

None

More information

See WordPress Developer Resources: rest_authorization_required_code

Examples

Custom REST API Endpoint Authorization

In this example, we create a custom REST API endpoint, and use rest_authorization_required_code to return an appropriate error code if the user is not authorized to access the endpoint.

function my_custom_api_endpoint( WP_REST_Request $request ) {
  if ( ! current_user_can( 'edit_posts' ) ) {
    return new WP_Error( 'rest_forbidden', 'Sorry, you are not allowed to access this endpoint.', array( 'status' => rest_authorization_required_code() ) );
  }

  // Continue processing the request...
}

Customizing REST API Authorization Error Response

Customize the error response for REST API authorization by using the rest_authorization_required_code function.

function my_custom_rest_authorization_error( $error ) {
  if ( ! empty( $error->errors['rest_forbidden'] ) ) {
    $error->errors['rest_forbidden'][0] = 'Sorry, you do not have permission to access this endpoint.';
    $error->error_data['rest_forbidden']['status'] = rest_authorization_required_code();
  }

  return $error;
}
add_filter( 'rest_authorization_error', 'my_custom_rest_authorization_error' );

Custom Endpoint for Non-Logged-In Users

Create a custom REST API endpoint for non-logged-in users, using rest_authorization_required_code to return an appropriate error code if the user is logged in.

function my_guest_api_endpoint( WP_REST_Request $request ) {
  if ( is_user_logged_in() ) {
    return new WP_Error( 'rest_forbidden', 'Sorry, this endpoint is only for non-logged-in users.', array( 'status' => rest_authorization_required_code() ) );
  }

  // Continue processing the request...
}

Handling Unauthorized REST API Requests

Handle unauthorized REST API requests by checking the status code returned by rest_authorization_required_code.

function handle_unauthorized_api_request( $response, $request ) {
  if ( ! is_wp_error( $response ) ) {
    return $response;
  }

  $error_code = $response->get_error_code();
  if ( $error_code === 'rest_forbidden' && $response->get_error_data( $error_code )['status'] === rest_authorization_required_code() ) {
    // Perform custom actions for unauthorized requests...
  }

  return $response;
}
add_filter( 'rest_request_after_callbacks', 'handle_unauthorized_api_request', 10, 2 );

Displaying a Custom Message for Unauthorized REST API Requests

Display a custom message for unauthorized REST API requests, using rest_authorization_required_code to check for the appropriate error status.

function display_custom_unauthorized_message( $result, $request, $permission_callback ) {
  if ( is_wp_error( $result ) && $result->get_error_data( 'rest_forbidden' )['status'] === rest_authorization_required_code() ) {
    $result->errors['rest_forbidden'][0] = 'Custom message: You do not have permission to access this endpoint.';
  }

  return $result;
}
add_filter( 'rest_dispatch_request