Scopes, Roles & Fine-Grained Authorization — API Security in Depth

Scopes describe what a client application may do on the user's behalf (orders:read) — they're coarse and belong in tokens. Permissions for a user on a specific resource (can Alice edit this document?) are fine-grained and usually decided at request time by a policy layer: RBAC (roles), ABAC (attributes such as department, region, time) or ReBAC (relationships, Google Zanzibar style: OpenFGA, SpiceDB). Keep tokens small; don't stuff every permission into a JWT.

Authorization models

Criterion	Scopes	RBAC	ABAC	ReBAC
Answers	What may this client do?	What may this role do?	Do attributes satisfy policy?	Is user related to object?
Granularity	API area	Function	Fine	Per object
Where evaluated	Token check at API	App/policy engine	Policy engine (OPA/Cedar)	Authz service (OpenFGA/SpiceDB)
Sharing ('share doc with Bob')	No	Awkward	Possible	Native
Example	invoices:write	role=accountant	region == user.region	viewer of folder → viewer of doc

allowed = await fga.check(ClientCheckRequest(
    user=f"user:{user.id}", relation="editor", object=f"document:{doc_id}"))
if not allowed.allowed:
    raise HTTPException(404)

permit (
  principal in Role::"accountant",
  action in [Action::"read", Action::"approve"],
  resource is Invoice
) when { resource.amount < 10000 && resource.region == principal.region };

Common pitfalls

Using scopes as user permissions (can_edit_doc_123).
Authorization logic copy-pasted across services.
Huge JWTs listing every permission.

Key points

Scopes = client delegation; permissions = user × resource
Centralize fine-grained decisions
ReBAC for sharing models

Further reading: OpenFGA: Authorization concepts

Practice questions

What's the difference between a scope and a permission?

Answer

A scope limits what a client application may do with the user's delegated authority; a permission says whether a user may do something to a particular resource.

When is relationship-based access control (ReBAC) a good fit?

Answer

When access derives from relationships and sharing — folders, teams, orgs, documents shared with users — like Google Drive or GitHub.