API Authorization: Models, Methods, and Best Practices
Most API breaches don't start with a stolen password. They start with a valid token that can reach too much. This guide explains how API authorization works, compares RBAC, ABAC, ReBAC and OAuth scopes, shows where to enforce each check, and walks through tested code that stops broken object-level access.

TL;DR:
What is API authorization?
API authorization is the check that decides what an authenticated caller may do: which operations it can call, which records it can touch, and under what conditions. APIs make that decision with models such as RBAC, ABAC, ReBAC and OAuth scopes.
Enforce coarse checks at the API gateway and object-level checks inside each service, on every request, and deny anything not explicitly allowed.
Salt Security's 2025 State of API Security report found that 95% of API attacks came from authenticated sources. The callers had valid credentials. Authentication worked. What failed was API authorization: nobody stopped a valid caller from reaching data that wasn't theirs.
The OWASP API Security Top 10 (2023) tells the same story. Three of its top five risks are authorization failures: broken object level authorization (API1), broken object property level authorization (API3) and broken function level authorization (API5).
This guide explains how API authorization works, compares the main models, shows where each check belongs, and walks through code we ran and tested.

What is API authorization?
API authorization is the decision about what a caller may do once the API knows who it is. It runs on every request, after authentication, and returns allow or deny. A good decision answers four questions, not one.
API authorization
API authorization is the process an API uses to decide whether an authenticated caller, such as a user, partner application, service or AI agent, may perform a specific action on a specific resource. The decision uses the caller's identity and permissions, the resource's properties and the request context, and the API returns 403 Forbidden when the answer is no.
Every authorization decision answers these four questions:
- Who is calling? The principal: a user, a partner app, a service or an AI agent, plus the tenant it belongs to.
- What do they want to do? The action: read, create, refund, export, delete.
- Which object? The resource: not "invoices" in general, but invoice
inv_2. - Under what conditions? The context: time, network, environment, amount, risk score.
Many APIs only answer the first two. That's how a caller with a valid invoices:read token ends up reading every invoice in the database by changing an ID in the URL.
What are the three levels of API authorization?
API authorization works at three levels: the function, the object and the property. Each one maps to an OWASP API Top 10 (2023) risk, so each needs its own check.
- Function level: can this caller use this operation at all, such as
POST /invoices/{id}/refund? Missing checks cause broken function level authorization (API5). - Object level: can this caller touch this particular record? Missing checks cause broken object level authorization (API1), the top API risk.
- Property level: can this caller see or change this field, such as
ibanorcredit_limit? Missing checks cause broken object property level authorization (API3).
How is API authorization different from API authentication?
Authentication proves who the caller is. Authorization decides what that caller may do. Authentication runs first and fails with 401 Unauthorized. Authorization runs on every request after it and fails with 403 Forbidden.
An API key, a client certificate or an OAuth access token answers "who". Roles, attributes, relationships, scopes and policies answer "what". For the full comparison, with real request examples, see authentication vs authorization. For the "who" side alone, see our guide to API authentication.
What are the main API authorization models?
The main API authorization models are RBAC (roles), ABAC (attributes), ReBAC (relationships), PBAC (central policies) and OAuth scopes (token permissions). Each one decides on different data. Most production APIs combine two or three of them.
API authorization models compared
| Model | Decides on | Example rule | Best for | Weak spot |
|---|---|---|---|---|
| RBAC (role-based) | The caller's role | finance can call refund endpoints | Internal teams, a few partner tiers | Role explosion when rules depend on context |
| ABAC (attribute-based) | Attributes of caller, resource and context | Caller's tenant must match the invoice's tenant | Multi-tenant APIs, plans, regions, data classes | Attributes must be trustworthy and kept current |
| ReBAC (relationship-based) | Links between the caller and the object | Owners and people it's shared with can read the invoice | Sharing, teams, folders, org hierarchies | Needs a relationship store kept in sync |
| PBAC (policy-based) | Central policies written as code | One Cedar or Rego policy for every API | Many services that need one rulebook | Needs a policy engine and policy testing |
| OAuth scopes | Permissions inside the access token | Token must carry invoices:refund | Partner apps, delegated access, AI agents | Too coarse for "this record" decisions |
Swipe sideways to see all columns →
These authorization models aren't rivals. Scopes cap what a token can ever do, roles say what a person is, attributes and relationships decide on the individual record, and a policy engine keeps all of it in one place.
What is RBAC for APIs?
Role-based access control grants API permissions to roles, then assigns roles to callers. A support role can read invoices, a finance role can also refund them. RBAC is easy to audit, but it can't express "only this tenant's invoices" without creating a role per tenant. We compare the two in detail in RBAC vs ABAC.
What is ABAC for APIs?
Attribute-based access control decides using attributes of the caller, the resource and the request. A rule such as "allow if caller.tenant == invoice.tenant and invoice.amount <= 1000" covers every tenant with one rule. NIST SP 800-162 defines the model. For examples and policy code, see what is ABAC.
What is ReBAC?
Relationship-based access control (ReBAC) allows access when a path of relationships links the caller to the object, such as "Ana is a viewer of invoice inv_2" or "Ana is a member of the team that owns the folder that contains it". It's the model behind sharing features.
Google described its version in the 2019 Zanzibar paper. Zanzibar authorization handles trillions of access control lists and millions of checks per second for Drive, Calendar, YouTube and other services, with 95th-percentile latency under 10 milliseconds. Open-source systems such as OpenFGA and SpiceDB follow the same design.
What is policy-based access control?
Policy-based access control (PBAC) moves authorization rules out of application code into central policies that a policy engine evaluates. Your API asks "may this caller do this?" and the engine answers. Common engines are Open Policy Agent (Rego), Cedar and OpenFGA. PBAC isn't a separate data model: a policy can express RBAC, ABAC and ReBAC rules side by side.
Where do OAuth scopes fit?
OAuth scopes limit what an access token can be used for, whoever holds it. They're the right tool for function-level limits on partner apps and agents, such as invoices:read versus invoices:refund. They can't say which invoice, so pair them with object-level checks. See OAuth scopes explained for scope design and enforcement.
RBAC alone is right for you if
- Your API serves internal teams or a few fixed partner tiers.
- Every caller with a role may see every record of that type.
- Auditors need a simple list of who can reach which API.
You need ABAC or ReBAC on top if
- Records belong to tenants, customers or users and must stay separate.
- Users share records with each other, or access follows teams and folders.
- Rules depend on amount, region, plan, data class or environment.
- You expose APIs to partners or AI agents that act for many end users.
What methods do APIs use to carry and check authorization?
API authorization methods fall into two groups: ways to carry permissions with the request, and ways to evaluate them. API keys, access tokens and certificates carry identity and permissions. Token validation, introspection and policy engines evaluate them.
API authorization methods
| Method | What it tells the API | Granularity | Use it for |
|---|---|---|---|
| API key | Which app or project is calling | Coarse: per app or plan | Identifying apps, quotas, low-risk public data |
| OAuth 2.0 access token with scopes | Which operations this token may use | Function level | Partner apps, user consent, AI agents |
JWT claims (sub, tenant, roles) | Who the subject is and their attributes | Input to object-level rules | Stateless checks at gateway and service |
| Token introspection (RFC 7662) | Whether an opaque token is active, and its scopes | Function level, revocable | High-risk APIs that need instant revocation |
| mTLS or DPoP sender-constrained tokens | That the caller holds the key bound to the token | Proof of possession | Open banking, payments, service-to-service |
| Policy engine (OPA, Cedar, OpenFGA) | Allow or deny for this caller, action and object | Object and property level | Fine-grained rules shared across services |
Swipe sideways to see all columns →
A few points matter in practice:
- API keys identify apps, not people. Treat a key as "who", then make the authorization decision from the plan or permissions linked to it.
- JWT claims are inputs, not decisions. A
rolesclaim tells you what the identity provider believes. Your API still decides what that role may do. - Bearer tokens work for whoever holds them. For high-value APIs, bind tokens to a key with mTLS (RFC 8705) or DPoP (RFC 9449), so a stolen token is useless on its own.
What is delegated authorization?
Delegated authorization lets one party act on another's behalf with limited, revocable rights, without sharing passwords. It's what OAuth 2.0 was built for. A user approves a partner app to read their invoices, and the app receives a token with invoices:read for that user only.
Delegation also happens between services. When an API calls another API for the user, it shouldn't forward the user's token unchanged. OAuth 2.0 Token Exchange (RFC 8693) lets it swap that token for a new one, scoped to the downstream API, that records both the user and the acting service. The downstream API then sees who the request is for and who is making it.
Where should you enforce API authorization: gateway or service?
Enforce API authorization in both places, with different checks in each. The API gateway handles coarse checks that need only the token and the route. The service handles fine checks that need the actual record. Neither layer is enough alone.

Gateway vs service: where each check runs
| Check | API gateway | Service |
|---|---|---|
| Token valid: signature, expiry, issuer | Yes | Yes, if reachable without the gateway |
| Audience: token issued for this API | Yes | Yes |
| Scope per route (function level) | Yes | Keep a backup check |
| Deny routes with no policy | Yes | Yes |
| Rate limits and quotas per app | Yes | No |
| Tenant and ownership of the record (object level) | No: the gateway hasn't loaded the record | Yes |
| Fields the caller may read or change (property level) | No | Yes |
| Business limits, such as refund amount | Rarely | Yes |
Swipe sideways to see all columns →
The pattern behind this split has standard names. The code that blocks or allows a request is the policy enforcement point (PEP). The component that makes the decision is the policy decision point (PDP). Your gateway and services are both PEPs. They can share one PDP, so the rules live in one place.
That interface is now standardised. The OpenID Foundation approved the AuthZEN Authorization API 1.0 as a final specification in January 2026. It defines how any PEP asks any PDP for a decision, so you can swap gateways or policy engines without rewriting every check.
How do you keep authorization consistent across API gateways?
Define each API's authorization policy once, and push it to every gateway that serves the API. Large organisations often run Kong, Apigee, AWS API Gateway and Azure API Management side by side. Each one has its own policy syntax, so the same rule drifts: one gateway checks the refund scope, another forgets the export route.
The DigitalAPI API Gateway applies one scope-to-route and deny-by-default policy across the gateways you already run, so a change to who can call an API happens once and shows up everywhere. Through the DigitalAPI API Developer Portal, partners request only the APIs and scopes their plan allows, so API access control starts narrow on the first token. For the broader gateway controls, see API gateway security.
See how DigitalAPI enforces one authorization policy across every gateway you run → Book a Demo
How do you implement fine-grained API authorization?
Fine grained authorization means deciding per object and per action, not per API. In practice that's one decision function that combines roles, attributes and relationships, called by the service after it loads the record. Here's a working version we tested.
The example is an invoices API with three rules:
- ABAC: callers only see invoices from their own tenant.
- ReBAC: callers can read an invoice they own or that was shared with them.
- RBAC plus ABAC: only the
financerole can refund, and only up to 1,000.
First, the policy decision point. It returns a decision and a reason, so every outcome can be logged:
// policy.mjs: one decision point that combines RBAC, ABAC and ReBAC
// Relationship tuples (ReBAC), as a tool like OpenFGA would store them
const relations = new Set([
'user:ana#owner@invoice:inv_1',
'user:ana#viewer@invoice:inv_2', // inv_2 is owned by ben and shared with ana
'user:ben#owner@invoice:inv_2',
]);
const has = (user, rel, obj) => relations.has(`user:${user}#${rel}@${obj}`);
// Every decision returns allow plus a reason, so you can log and audit it
export function authorize(principal, action, resource) {
// ABAC: the caller's tenant must match the resource's tenant
if (principal.tenant !== resource.tenant) return { allow: false, reason: 'tenant_mismatch' };
const obj = `invoice:${resource.id}`;
switch (action) {
case 'invoice:read': // ReBAC: owners and viewers can read
return has(principal.sub, 'owner', obj) || has(principal.sub, 'viewer', obj)
? { allow: true, reason: 'relation' } : { allow: false, reason: 'no_relation' };
case 'invoice:refund': // RBAC + ABAC: finance role, under the amount limit
if (!principal.roles.includes('finance')) return { allow: false, reason: 'role_required' };
return resource.amount <= 1000
? { allow: true, reason: 'finance_within_limit' } : { allow: false, reason: 'over_limit' };
default: // deny by default
return { allow: false, reason: 'unknown_action' };
}
}Next, the API. Layer 1 does what a gateway does: it validates the token and checks the scope for the route. Layer 2 runs in the service: it loads the invoice and asks the policy for a decision.
// api.mjs: layer 1 (gateway checks) + layer 2 (object checks in the service)
// Node.js 18+, jose 5.x, Express 4.x
import express from 'express';
import { jwtVerify } from 'jose';
import { authorize } from './policy.mjs';
export function buildApi({ publicKey, issuer, audience }) {
// Layer 1a: authentication. Who is calling, and is the token for this API?
async function authenticate(req, res, next) {
const [scheme, token] = (req.headers.authorization || '').split(' ');
if (scheme !== 'Bearer' || !token) return res.status(401).set('WWW-Authenticate', 'Bearer').end();
try {
const { payload } = await jwtVerify(token, publicKey, { algorithms: ['RS256'], issuer, audience });
req.principal = { sub: payload.sub, tenant: payload.tenant, roles: payload.roles || [],
scopes: new Set((payload.scope || '').split(' ')) };
next();
} catch {
res.status(401).set('WWW-Authenticate', 'Bearer error="invalid_token"').end();
}
}
// Layer 1b: function-level authorization. Does the token allow this operation at all?
const requireScope = (scope) => (req, res, next) => req.principal.scopes.has(scope) ? next()
: res.status(403).set('WWW-Authenticate', `Bearer error="insufficient_scope", scope="${scope}"`).end();
// Layer 2: object-level authorization inside the service, after loading the record
const invoices = { inv_1: { id: 'inv_1', tenant: 'acme', amount: 400 },
inv_2: { id: 'inv_2', tenant: 'acme', amount: 5000 },
inv_9: { id: 'inv_9', tenant: 'globex', amount: 90 } };
const check = (action) => (req, res, next) => {
const invoice = invoices[req.params.id];
if (!invoice) return res.status(404).end();
const d = authorize(req.principal, action, invoice);
console.log(JSON.stringify({ sub: req.principal.sub, action, id: invoice.id, ...d })); // audit log
if (d.allow) return next();
return d.reason === 'tenant_mismatch' ? res.status(404).end() // don't reveal other tenants' records
: res.status(403).json({ error: d.reason });
};
return express()
.get('/invoices/:id', authenticate, requireScope('invoices:read'), check('invoice:read'),
(req, res) => res.json({ id: req.params.id }))
.post('/invoices/:id/refund', authenticate, requireScope('invoices:refund'), check('invoice:refund'),
(req, res) => res.status(202).json({ refund: 'queued' }))
.use((req, res) => res.status(404).end()); // unmapped routes: deny by default
}We ran 11 requests against this API with signed test tokens. Every result matched the rules:
API authorization test results
| Request | Result |
|---|---|
| No token | 401, WWW-Authenticate: Bearer |
Token issued for another API (wrong aud) | 401, invalid_token |
| Ana reads her own invoice | 200 |
| Ana reads an invoice shared with her | 200 |
| Fay reads a same-tenant invoice not shared with her | 403, no_relation |
| Ana reads another tenant's invoice | 404 |
| Ana refunds with a read-only token | 403, insufficient_scope, scope="invoices:refund" |
| Ana has the refund scope but not the finance role | 403, role_required |
| Finance refunds an invoice of 400 | 202 |
| Finance refunds an invoice of 5,000 | 403, over_limit |
| Unmapped admin route | 404, denied by default |
Swipe sideways to see all columns →

Two results are worth a closer look. Fay's request had a valid token, the right scope and the right tenant, and still failed: only the relationship check caught it. That's exactly the gap behind broken object level authorization. And Ana's refund failed even though her token carried invoices:refund, because a scope says what the token may do, not what Ana may do.
Why return 404 instead of 403 for another tenant's record?
Return 404 when the record belongs to another tenant, so callers can't learn which IDs exist. A 403 confirms that invoice inv_9 is real, which helps an attacker map your data. Inside the caller's own tenant, 403 with a reason is fine and makes debugging easier. Log the true reason either way.
Should authorization rules live in code or in a policy engine?
Start with one decision function in code; move to a policy engine when several services need the same rules. The authorize() function above is already a small PDP. When five services copy it, the copies drift. At that point, put the rules in Cedar, Rego or an OpenFGA model, test them like code, and have every service and gateway ask the same engine.
How does API authorization work for AI agents and MCP?
Treat each AI agent as its own client with its own narrow, short-lived permissions, and check every tool call like any other API request. Agents chain calls fast and without a human watching, so broad access turns one bad prompt into a large incident.
- Give each agent its own identity. Don't let agents reuse a human's session or a shared service key.
- Delegate, don't impersonate. When an agent acts for a user, use token exchange so the token records both the user and the agent, and is scoped to the one API it needs.
- Map tools to scopes. One scope per group of tools, such as
tickets:readandtickets:write, with export and delete behind their own scopes. - Keep object-level checks in the API. An agent asking for invoice
inv_2must pass the same tenant and relationship checks as a person. - Require a human for high-risk actions. Refunds, deletions and bulk exports should need explicit approval.
The MCP authorization specification builds on OAuth: MCP servers publish their requirements with Protected Resource Metadata (RFC 9728), clients name the target server with resource indicators (RFC 8707), and servers must reject tokens issued for anyone else. For setup steps, see securing MCP endpoints.
What are API authorization best practices?
The core API authorization best practices are: deny by default, check every request at every level, keep permissions narrow and short-lived, and decide from one policy you can test and audit. The UK National Cyber Security Centre's 2025 API guidance puts it as "Validate permissions on every request."
- Deny by default. A route, action or field with no policy is blocked, not open.
- Check authorization on every request. Don't cache "this user is fine" across calls, sessions or pages.
- Check all three levels. Function level at the gateway, object and property level in the service.
- Check the object, not the ID format. Random UUIDs make IDs harder to guess, but they don't replace an ownership check.
- Never trust identity from the request body or headers the client controls. Take
sub,tenantandrolesfrom a validated token or your own records. - Check audience as well as scope. A token issued for the billing API must fail on the invoices API.
- Grant least privilege, then review it. Microsoft's 2023 State of Cloud Permissions Risks report found identities used only 1% of the permissions they were granted, and more than 50% were super admins. Remove what callers don't use.
- Keep tokens short-lived. Minutes, not months, so revoked access ends quickly. Bind high-value tokens to a key with mTLS or DPoP.
- Centralise the decision, distribute the enforcement. One PDP and policy, many PEPs at the gateways and services.
- Log every decision with its reason. Who, what action, which object, allowed or denied, and why. Auditors and incident responders need all five.
- Test authorization like features. Write tests for "user A can't read user B's record" for every endpoint, and run them in CI.
Narrow permissions matter because credentials leak. The Verizon 2025 Data Breach Investigations Report found credential abuse was the most common way attackers got in, at 22% of breaches. Good API authorization doesn't stop a credential leaking. It limits what that credential can reach.
What are the most common API authorization mistakes?
Most API authorization failures come from checks that are missing at one level, trust the wrong input, or differ between gateways. These are the ones we see most often:
Common API authorization mistakes and fixes
| Mistake | What happens | Fix |
|---|---|---|
| Checking only that the caller is logged in | Any user reads any record by changing the ID (BOLA) | Check ownership, tenant or relationship for every object |
| Checking scope but not the user's rights | A token with invoices:refund lets any holder refund | Combine scope with role, attribute and relationship checks |
| Hiding admin endpoints instead of protecting them | Attackers find /admin routes and call them (BFLA) | Deny unmapped routes; require explicit admin permissions |
| Returning whole objects | Callers see fields they shouldn't, such as iban | Filter response fields per caller (property level) |
| Accepting mass updates | Callers set role=admin or price=0 in a PATCH | Allowlist the fields each caller may change |
| Trusting a tenant ID from a header | Callers switch tenants by editing one header | Take tenant from the validated token or your database |
| Authorization only at the gateway | Internal calls that skip the gateway skip every check | Keep object-level checks in each service |
| Each team writes its own rules | Same role means different things in different APIs | One policy, one decision point, shared tests |
| Shared credentials for agents and scripts | No way to tell who did what, or revoke one caller | One client identity per app, service and agent |
| No decision logs | You can't prove who accessed what | Log every allow and deny with a reason |
Swipe sideways to see all columns →
Key takeaways
- API authorization decides what an authenticated caller may do: which operation, on which object, under what conditions.
- Check three levels: function (the route), object (the record) and property (the field). BOLA, the top OWASP API risk, is a missing object-level check.
- Combine models: scopes cap the token, roles describe the person, attributes and relationships decide on the record, and a policy engine keeps it all in one place.
- Enforce in layers: token, audience and scope at the gateway; tenant, ownership and fields in the service.
- Deny by default, keep permissions narrow and short-lived, and log every decision.
Frequently asked questions
1. What is API authorization?
API authorization is the process an API uses to decide whether an authenticated caller may perform a specific action on a specific resource. It runs on every request after authentication, uses the caller's permissions, the resource's properties and the request context, and returns 403 Forbidden when access is denied.
2. What is the difference between API authentication and authorization?
API authentication verifies who is calling, using an API key, certificate or access token, and fails with 401 Unauthorized. API authorization decides what that caller may do, using roles, scopes, attributes or policies, and fails with 403 Forbidden. Authentication happens once per request; authorization can happen several times, at the route, the object and the field.
3. What are the three types of authorization?
The three most common authorization models are role-based access control (RBAC), which grants access by role; attribute-based access control (ABAC), which decides using attributes of the caller, resource and context; and relationship-based access control (ReBAC), which allows access when the caller is linked to the object, such as an owner or viewer. Most APIs combine them.
4. What is fine-grained authorization?
Fine-grained authorization is access control that decides per object, action and condition, rather than per API or role. For example, "Ana can read invoice inv_2 because it was shared with her" is fine-grained; "support can read invoices" is coarse. It's usually built with ABAC or ReBAC rules evaluated by a policy engine.
5. Where should API authorization be enforced?
API authorization should be enforced at both the API gateway and the backend service. The gateway checks the token, audience and required scope for each route, and blocks unmapped routes. The service checks object-level and field-level rules, such as tenant and ownership, because only the service has loaded the record.
6. What is broken object level authorization?
Broken object level authorization (BOLA) is when an API checks that a caller is logged in but not whether they may access the specific record requested. An attacker changes an ID in the URL, such as /invoices/124 to /invoices/125, and reads someone else's data. It's API1, the top risk, in the OWASP API Security Top 10 (2023).
7. Is OAuth an authorization method?
Yes. OAuth 2.0 is a delegated authorization framework: it lets an app get a limited access token to call an API on a user's or its own behalf. The token's scopes limit which operations it can use. OAuth doesn't decide which individual records a caller may see, so APIs still need object-level checks.
8. What is delegated authorization?
Delegated authorization lets one party act for another with limited rights, without sharing passwords. In OAuth, a user approves an app, and the app receives a token scoped to that user and those permissions. Between services, OAuth Token Exchange (RFC 8693) issues a new, narrower token that records both the user and the acting service or agent.
9. Should an API return 403 or 404 when access is denied?
Return 403 Forbidden when the caller may know the resource exists but isn't allowed to act on it. Return 404 Not Found when revealing that the resource exists would leak information, such as a record that belongs to another tenant. Return 401 only when the token is missing, expired or invalid.
10. What is a policy engine in API authorization?
A policy engine is a service or library that evaluates authorization rules and returns allow or deny. Your API sends the caller, action and resource; the engine applies policies written in a language such as Rego (Open Policy Agent) or Cedar. Using one engine keeps rules consistent across services and lets you test and audit them in one place.
Conclusion
Most API incidents don't involve breaking authentication. They involve a valid caller reaching something it shouldn't. API authorization is the control that stops that, and it only works when it answers all four questions: who, what action, which object and under what conditions.
Use scopes to cap what each token can do, roles to describe people, attributes and relationships to decide on each record, and one policy to keep the rules consistent. Enforce coarse checks at the gateway, object checks in the service, deny by default, and log every decision. For the wider picture of keys, tokens and roles, read the ultimate guide to API access control.
How safely do you grant API access to partners and AI agents? Get your free readiness score: Check Your API Access Readiness
Prefer a walkthrough? Book a Demo
One email a fortnight. Worth opening.
A short digest of what we're writing, what we're learning from customers, and the handful of links you'd actually want from us. No tracking pixels.













.avif)
