Protecting an API with Scopes and Permissions

API scopes describe allowed actions but every request still requires server-side authorization for its resource.

What It Does

API scopes describe allowed actions but every request still requires server-side authorization for its resource. The following examples distinguish a normal use case, a boundary case and a practical application.

Requirements and Compatibility

PHP 8.x and a local test environment. Apply input validation, correct error handling and the requirements of any optional libraries.

The code focuses on the core concept. Production implementation may also need routes, validation, persistence, authorization or deployment tooling.

Example 1: Basic Behavior

Enforce an action scope only after validating the token itself.

<?php
$claims = ["scope" => "orders:read products:read"];
$scopes = explode(" ", $claims["scope"]);
if (!in_array("orders:read", $scopes, true)) { http_response_code(403); exit; }
echo "Scope accepted";
// The bearer token must be cryptographically validated before reading claims.

Example 2: Another Case

Reject cross-tenant access even when the bearer has a matching scope.

<?php
$actor = ["tenant" => 3, "scopes" => ["orders:read"]];
$order = ["tenant" => 4, "id" => 21];
$allowed = $actor["tenant"] === $order["tenant"] && in_array("orders:read", $actor["scopes"], true);
var_dump($allowed);

Practical Example: Putting It to Use

Combine action permission with object-level ownership before mutation.

<?php
function authorize(array $user, string $action, array $object): bool { return in_array($action, $user["permissions"], true) && $user["id"] === $object["owner_id"]; }
var_dump(authorize(["id" => 3, "permissions" => ["edit"]], "edit", ["owner_id" => 3]));

Important Behavior and Edge Cases

A valid bearer token does not automatically grant access to another user's or tenant's resource.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• API scopes describe allowed actions but every request still requires server-side authorization for its resource.
• A valid bearer token does not automatically grant access to another user's or tenant's resource.
• Combine token scope checks with ownership and tenant isolation.

Before adapting these examples, verify the return values, test the failure paths and confirm that your application meets its security and environment requirements.