OAuth2 Bearer Token Usage — RFC 6750 Token Transmission Standard

In this tutorial, you will learn about OAuth2 Bearer Token Usage. We cover key concepts, practical examples, and best practices to help you master this topic.

RFC 6750 defines how OAuth2 Bearer tokens are transmitted in HTTP requests, including the Authorization header format, error responses, and WWW-Authenticate challenges.

What You'll Learn

The standard Bearer token format, how servers challenge clients, error responses, and security considerations for token transmission.

Why It Matters

RFC 6750 is the standard for OAuth2 token transmission. Every OAuth2-compliant API uses it. Understanding it ensures interoperability with OAuth2 libraries and providers.

Real-World Use

Every major OAuth2 provider (Google, GitHub, Auth0) implements RFC 6750. The Authorization: Bearer <token> format is universal across OAuth2 implementations.

flowchart LR
    A["Client"] -->|"Authorization: Bearer "| B["Resource Server"]
    B -->|"Valid"| C["200 OK"]
    B -->|"Invalid token"| D["401 + WWW-Authenticate"]
    B -->|"Insufficient scope"| E["403 + WWW-Authenticate"]
    style A fill:#dbeafe,stroke:#2563eb
    style B fill:#fef3c7,stroke:#d97706
    style C fill:#dcfce7,stroke:#16a34a
    style D fill:#fecaca,stroke:#dc2626
    style E fill:#fecaca,stroke:#dc2626

Bearer Token Format

Authorization: Bearer <token-value>

The token value is case-sensitive and should not be encoded or transformed. The word "Bearer" is case-insensitive by convention.

WWW-Authenticate Challenges

from flask import make_response, jsonify

@app.route("/api/resource")
def get_resource():
    auth = request.headers.get("Authorization")
    if not auth:
        response = make_response(jsonify({"error": "unauthorized"}), 401)
        response.headers["WWW-Authenticate"] = (
            'Bearer realm="api", '
            'error="invalid_token", '
            'error_description="The access token is missing"'
        )
        return response

    token = auth[7:] if auth.startswith("Bearer ") else None
    if not token:
        response = make_response(jsonify({"error": "invalid_request"}), 401)
        response.headers["WWW-Authenticate"] = (
            'Bearer realm="api", '
            'error="invalid_request", '
            'error_description="Authorization header must use Bearer scheme"'
        )
        return response

    # Validate token...

Error Codes

Common Mistakes

1. Not Returning WWW-Authenticate Header

RFC 6750 requires the server to include WWW-Authenticate with 401 and 403 responses.

2. Using Wrong Error Codes

Returning 403 for missing token (should be 401) or 401 for insufficient scope (should be 403).

3. Case-Sensitivity Issues

The Authorization header value after "Bearer " is case-sensitive. Do not transform the token.

4. Including Extra Characters

The space after Bearer is required. Bearer<token> without space is invalid.

5. Logging Authorization Headers

Authorization headers contain credentials. Redact or sanitize before logging.

Practice Questions

1. What RFC defines Bearer token usage?
2. What is the correct format for the Bearer Authorization header?
3. What status code is returned for an expired token?
4. What status code is returned for insufficient scope?
5. What header does the server include in error responses?

Answers:

1. RFC 6750 — Bearer Token Usage.
2. Authorization: Bearer <token-value>.
3. 401 Unauthorized with error="invalid_token".
4. 403 Forbidden with error="insufficient_scope".
5. WWW-Authenticate with realm, error, and error_description parameters.

Challenge: Implement RFC 6750-compliant error handling in a Flask resource server. Include proper WWW-Authenticate headers for all error conditions.

FAQ

Mini Project

Build an RFC 6750-compliant resource server with proper Bearer token extraction, WWW-Authenticate error responses, and three error scenarios (missing token, invalid token, insufficient scope).

What's Next

Now learn the differences between OAuth2 vs OAuth1 — two different approaches to authorization.