Learn IAM
Learn IAM

Authorization for APIs: Scopes, Claims, and “Who Can Call What”

Authorization for APIs: Scopes, Claims, and “Who Can Call What”

For APIs, authorization lives in your token design.

But tokens are not magic: they are statements that must be validated and interpreted correctly.

The three questions

  1. Who is calling? (subject: user, client, workload)
  2. What are they trying to do? (action)
  3. What are they trying to do it to? (resource)

Scopes vs roles vs claims

  • Scopes: typically client-requested permissions (read:invoices). Good for APIs.
  • Roles: human-friendly bundles of privileges. Good for admin UX.
  • Claims: structured attributes (tenantId, userId, groups). Useful, but risky if they grow unbounded.

A practical approach:

  • Use scopes to represent API capabilities.
  • Use claims for stable identifiers (subject, tenant, audience).
  • Use roles/relationships in the authorization layer (database/PDP), not as huge token payloads.

Avoiding common mistakes

Confused deputy

If service A calls service B “on behalf of” a user, ensure:

  • the token audience is correct
  • delegation is explicit (OBO / token exchange)
  • B verifies both the user and the calling service

Over-trusting groups

Group membership can be huge and dynamic. Avoid putting it all in tokens.

Where to go next