REST API Authentication, Authorization, and Versioning

REST API•Permalink

Bearer auth, API keys, permission errors, versioning strategies, and compatibility patterns for HTTP APIs.

View

Standard Detailed Compact

Export

Copy the compact sheet, download it, or print it.

Download

`D` dense toggle · `C` copy all

Authentication patterns

Use standard auth headers and do not leak secrets in URLs.

Bearer token header

Send an OAuth or JWT access token.

↗#

httpANYrestauthbearer

http

Authorization: Bearer eyJhbGciOi...

Bearer tokens are the most common auth mechanism for modern APIs.

API key header

Send a static API key in a header.

↗#

httpANYrestapi-keyheaders

http

X-API-Key: sk_live_123456

If you support API keys, prefer headers over query parameters to reduce accidental leakage in logs and URLs.

Do not put tokens in the URL

Keep credentials out of path and query strings.

↗#

textANYrestsecurityanti-pattern

text

Avoid: GET /reports?access_token=abc123

URLs are frequently logged, cached, and copied, making them a poor place for secrets.

Return 403 for insufficient role

Authenticated but lacks required permission.

↗#

httpANYrestauthz403

http

HTTP/1.1 403 Forbidden

Use 403 when the user is known but does not have the right scope, role, or entitlement.

Versioning strategies

Introduce breaking changes without surprising existing clients.

Path-based versioning

Explicit major version in the URL.

↗#

httpANYrestversioningpath

http

GET /v1/users

Path versioning is simple and highly visible, making it popular for public APIs.

Media type versioning

Negotiate version with the Accept header.

↗#

httpANYrestversioningaccept-header

http

Accept: application/vnd.example.v2+json

This keeps URLs stable but can make testing and documentation slightly more complex.

Date-based compatibility header

Pin behavior by release date.

↗#

httpANYrestversioningheaders

http

API-Version: 2026-03-01

Some APIs version behavior by date rather than integer versions, especially when changes are incremental.

Signal deprecations clearly

Warn clients before removing behavior.

↗#

httpANYrestdeprecationsunset

http

Deprecation: true
Sunset: Tue, 01 Sep 2026 00:00:00 GMT

Deprecation signals help clients migrate before a breaking removal.

More in REST API

REST API Best Practices and Anti-Patterns

High-signal design rules, consistency patterns, and common mistakes to avoid in production APIs.

REST API Request and Response Patterns

JSON request bodies, envelope choices, sparse fieldsets, includes, concurrency control, and common response contracts.

REST API Status Codes and Error Response Design

Practical HTTP status codes, error response bodies, validation failures, and troubleshooting-friendly API error contracts.

REST API Pagination, Filtering, Sorting, and Search

Common collection query patterns including offset pagination, cursor pagination, filtering, sorting, and search.

REST API Resource Naming and URL Design

Naming conventions for resources, relationships, nested endpoints, and clean URL design.

REST API Methods and Idempotency

HTTP methods, safe vs unsafe semantics, and idempotency examples for API consumers and designers.

Recommended next

No recommendations yet.

Browse all sheets →