Authorization

Build systems that decide exactly what authenticated users can and cannot do with your API endpoints.

Authentication answers "who are you?" Authorization answers "what can you do?" These two concepts work together but solve completely different problems.

Think of authentication as your employee badge getting you through the front door of a building. Authorization is the different key cards that let you into specific floors, meeting rooms, or restricted areas once you are inside.

The APIForge Security team just finished building their authentication system using JWT tokens. Now they need authorization to control what different user roles can do with their developer platform APIs. Some users should read documentation, others should create API keys, and admin users should manage billing across multiple teams.

The Authorization Problem

Without proper authorization, your API becomes an all-or-nothing system. Users either have complete access to everything or no access at all. This creates massive security risks and makes it impossible to build applications with different user roles.

GitHub's API demonstrates sophisticated authorization in action. Repository owners can push code and manage settings. Collaborators might have write access but cannot delete the entire repository. Public repositories allow anyone to read code but not modify it. Each permission maps to specific API endpoints and HTTP methods.

Core Authorization Concepts

The subject represents who or what is making the request. This could be a user account, an API client, a service account, or even an anonymous visitor. Subjects carry attributes like user ID, role, team membership, or subscription level.

The action describes what the subject wants to do. In HTTP APIs, actions often map to HTTP methods like GET, POST, PUT, or DELETE. But actions can be more granular than HTTP methods - like "invite user," "export data," or "change billing settings."

The resource identifies what the subject wants to access or modify. Resources can be specific entities like "user account 12345" or "document abc-def" or broader categories like "all team members" or "billing information."

Role-Based Access Control (RBAC)

Stripe's API uses RBAC extensively. A "Developer" role might include permissions to create test charges and view API logs. A "Finance" role could access real transaction data and generate reports. An "Administrator" role would have permissions to manage account settings and invite team members.

RBAC works well when you can predict the types of users your API will serve. But it starts breaking down when you need more granular control or when roles overlap in complex ways.

// APIForge RBAC permission check before creating API keys
const user = await getCurrentUser(token);
const requiredRole = 'developer';
const requiredPermission = 'create_api_key';

if (user.role === requiredRole || user.permissions.includes(requiredPermission)) {
  // Allow API key creation
  const newApiKey = await generateApiKey(user.id);
  return { success: true, apiKey: newApiKey };
} else {
  return { error: 'Insufficient permissions', code: 'FORBIDDEN' };
}

Attribute-Based Access Control (ABAC)

ABAC policies can consider time of day, user location, device type, resource sensitivity level, and countless other attributes. A policy might allow file deletion only if the user created the file, it is during business hours, and the user is connecting from a corporate network.

Google Workspace APIs use sophisticated attribute-based authorization. Whether you can access a document depends on your organization role, the document's sharing settings, your relationship to the document owner, and sometimes even your physical location.

Resource-Level Authorization

Consider a project management API where users can belong to multiple teams and work on different projects. A user might have "read" access to Project A, "write" access to Project B, and "admin" access to Project C. Their role alone cannot determine what they can do - you need to check permissions for each specific resource.

Notion's API exemplifies resource-level authorization. Users can have different permissions for different pages, databases, and workspaces. Some pages might be shared with read-only access while others allow full editing capabilities.

// APIForge resource-level check for team analytics access
async function checkAnalyticsAccess(userId, teamId) {
  const membership = await TeamMembership.findOne({
    user_id: userId,
    team_id: teamId
  });
  
  if (!membership) {
    return { allowed: false, reason: 'NOT_MEMBER' };
  }
  
  if (membership.role === 'admin' || membership.permissions.includes('view_analytics')) {
    return { allowed: true, level: membership.role };
  }
  
  return { allowed: false, reason: 'INSUFFICIENT_PERMISSIONS' };
}

HTTP Status Codes for Authorization

Status code 401 Unauthorized means authentication is required or has failed. The client needs to provide valid credentials or refresh their token. Status code 403 Forbidden means the client is authenticated but lacks permission for the requested action.

Many APIs incorrectly return 401 for authorization failures, which confuses client developers. If a user is logged in but cannot access admin endpoints, that is a 403 Forbidden, not 401 Unauthorized.

Authorization Headers and Tokens

The Authorization header serves double duty - it provides authentication credentials and often contains authorization context. A JWT might include both user identity and their granted permissions in a single token.

Some APIs use separate headers for fine-grained authorization context. A user might authenticate with one token but specify which organization or project context applies to their current request using additional headers.

# APIForge API call with authorization context headers
GET /api/v1/teams/backend/analytics HTTP/1.1
Host: api.apiforge.dev
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Team-Context: backend-engineering
X-Permission-Scope: analytics:read
Content-Type: application/json

Implementing Authorization Middleware

Express.js applications commonly implement authorization as middleware functions that can be composed and reused across different routes. The middleware extracts user information from tokens, loads their permissions, and either allows the request to proceed or returns an authorization error.

Modern authorization middleware often integrates with external services like Auth0, AWS IAM, or Google Cloud IAM to avoid building complex permission systems from scratch. These services handle the hard parts while your middleware focuses on enforcing decisions.

// APIForge authorization middleware with role and resource checking
function requirePermission(permission, resourceType) {
  return async (req, res, next) => {
    try {
      const user = req.user; // Set by authentication middleware
      const resourceId = req.params.id;
      
      // Check role-based permission
      if (user.permissions.includes(permission)) {
        return next();
      }
      
      // Check resource-specific permission
      if (resourceType && resourceId) {
        const hasResourceAccess = await checkResourcePermission(
          user.id, resourceType, resourceId, permission
        );
        if (hasResourceAccess) {
          return next();
        }
      }
      
      return res.status(403).json({
        error: 'Insufficient permissions',
        required: permission
      });
    } catch (error) {
      return res.status(500).json({ error: 'Authorization check failed' });
    }
  };
}

Authorization Testing Strategies

Authorization tests should cover positive cases where access is granted, negative cases where access is denied, and edge cases around permission boundaries. Test with different user roles, resource ownership scenarios, and permission combinations.

Automated testing becomes crucial because manual testing cannot cover all permission combinations reliably. A single API endpoint might need different authorization behavior for administrators, resource owners, team members, and anonymous users.

Quiz