CH09-03: Authentication, Authorization, Rate Limits, and Versioning

Goal

The previous section introduced API Management as the gateway boundary. This section focuses on four controls that make API contracts safe to use over time: authentication, authorization, rate limits, and versioning.

These controls are often discussed separately, but they belong together architecturally. They decide who can call, what they can do, how much load they can send, and how the API can change without breaking consumers unexpectedly.

The durable idea is:

API controls protect both consumers and backends by making access and change explicit.

The Short Version

An API platform should not treat every caller the same.

A mobile app, partner system, internal dashboard, and backend service may all call an API, but they may need different identities, permissions, limits, versions, and support rules. Good API design makes those differences explicit.

Use this starting model:

flowchart LR
    C["Client"]
    A["Authentication<br/><small>Who is calling?</small>"]
    Z["Authorization<br/><small>What may they do?</small>"]
    L["Limits<br/><small>How much traffic is allowed?</small>"]
    V["Versioned contract<br/><small>Which API shape is expected?</small>"]
    B["Backend service"]

    C --> A --> Z --> L --> V --> B

This is a logical flow, not a strict implementation order for every policy. The important idea is that access and change are part of the API contract.

Authentication and Authorization Are Different

Authentication proves the caller's identity.

For APIs, authentication might involve Microsoft Entra ID tokens, OAuth 2.0-style access tokens, managed identities for service-to-service calls, certificates, subscription keys, or partner credentials. The exact pattern depends on the consumer and security requirements.

Authorization decides what the authenticated caller may do.

For example:

• A mobile user may read their own orders.

• A partner may read fulfillment status for orders assigned to that partner.

• An internal support user may read broader customer information, but only with audit logging.

• A backend service may create fulfillment work, but not read payment details.

Authentication answers, "Who is this?" Authorization answers, "What is this identity allowed to do?"

API Management can help validate tokens, check claims, require subscription access, and apply policies. Backend services still need to enforce domain authorization when the decision depends on business data. A gateway can reject a token that lacks a required scope. The backend may still need to check whether this caller can access this specific customer, order, tenant, or account.

Products, Subscriptions, Scopes, and Roles

API access usually combines several ideas.

These controls should reinforce each other. A subscription key alone may identify an application or subscription, but it is not the same as user authentication. A token may prove a caller, but it does not automatically mean every operation is allowed. Backend authorization remains important when data sensitivity or business rules matter.

Rate Limits and Quotas

Rate limits and quotas protect the platform from overload and unfair usage.

A rate limit usually controls traffic over a short time window, such as requests per minute. A quota usually controls usage over a longer window, such as requests per day or month. Exact implementation details vary, but the architecture purpose is consistent.

They help answer:

• How much traffic can this consumer send?

• Should partner traffic be capped differently from internal traffic?

• How do we protect a fragile backend during spikes?

• How do we prevent one consumer from harming others?

• What response should callers receive when they exceed limits?

Rate limits are not only a punishment for bad consumers. They are a capacity and fairness tool. They make expectations visible. They also force teams to discuss backend limits before traffic arrives.

Versioning and Safe Change

APIs are contracts, so changing them carelessly breaks trust.

Some changes are usually safer:

• Adding an optional field to a response.

• Adding a new operation.

• Supporting a new query parameter that is optional.

Some changes are risky or breaking:

• Removing a field consumers depend on.

• Renaming a property.

• Changing error behavior.

• Changing required request fields.

• Changing meaning without changing the shape.

• Tightening authorization in a way that breaks existing approved consumers.

Versioning gives teams a way to expose new behavior while existing consumers migrate. Deprecation gives consumers notice that an old version will eventually be retired. Backward compatibility reduces the number of forced migrations.

Good versioning is partly technical and partly social. Consumers need documentation, timelines, test environments, migration guidance, and communication. A new route or header is not enough if nobody knows what changed.

Example: One Customer API, Different Consumers

Imagine a customer API used by a mobile app, a partner system, and an internal dashboard.

The API route may look similar for each caller. The contract responsibilities are different.

Common Mistakes

• Confusing authentication with authorization.

• Giving every consumer the same policy.

• Treating subscription keys as a complete security model.

• Breaking consumers by changing API contracts without a versioning or deprecation plan.

• Adding rate limits without telling consumers what the limits mean or how errors are returned.

• Enforcing coarse gateway access but forgetting backend data-level authorization.

If Someone Asks You

How should an API platform control access and change?

A good answer is:

An API platform should authenticate callers, authorize what they may do, apply rate limits and quotas that protect backends and consumer fairness, and manage versions so contracts can change safely. API Management can centralize many boundary controls, but backend services still enforce domain-specific authorization and data rules.

What You Should Remember

API platforms need explicit caller identity, allowed actions, traffic limits, and contract lifecycle rules.

Questions to Check Understanding

1. Why are authentication and authorization separate concerns?

2. What risks do rate limits reduce?

3. Why does versioning matter to consumer trust?

4. Which authorization decisions may still belong in the backend service?