FastAPI Authentication with JWT and OAuth2: Secure API Guide


APIs often expose customer records, business operations, private documents and other resources that should not be available to every caller. Authentication establishes who or what is making a request. Authorization determines what that authenticated identity is allowed to do. A secure FastAPI application needs both: confirming a user's identity is only the first step, and every protected operation must still enforce the correct permissions.
FastAPI provides a flexible foundation for implementing authentication. Its dependency injection system allows security checks to be shared across routes, its type hints and Pydantic models validate incoming data, and its OpenAPI integration documents supported authentication schemes. FastAPI does not, however, automatically create a complete identity provider, user database, password policy, token revocation service or authorization model. Those responsibilities must be designed deliberately or delegated to a trusted identity platform.
This guide explains how JWTs work, how OAuth 2.0 and OpenID Connect fit together, and how to protect FastAPI endpoints using current security practices. It includes Python examples for password hashing, bearer-token validation, trusted JSON Web Key Sets, authorization scopes, error handling and testing. It also explains why some older tutorials use an OAuth2 password grant that should not be selected for new applications.
The examples focus on the API's role as a resource server: a client obtains an access token through a trusted identity provider and presents that token to FastAPI. This is a common architecture for production systems because the identity provider manages sign-in, account recovery, multi-factor authentication and delegated authorization, while the API concentrates on its own resources and permissions.
These terms are related, but they describe different parts of an identity system.
Authentication verifies an identity. A user might prove control of an account through a password, passkey, authenticator application, hardware security key or an identity provider. A service might authenticate with a client credential or workload identity.
After authentication, the system needs a trustworthy representation of the identity. This may be a user ID, subject identifier, service account or another stable principal. Do not use an email address as the only permanent identifier if users can change it.
Authorization evaluates permissions. A signed-in user may be allowed to read their own profile but not another user's profile. A support agent may view selected customer records but not change billing settings. An administrator may manage users but still be restricted from accessing unrelated tenants.
Authentication should not be treated as proof of authorization. Every sensitive operation needs server-side permission checks, including checks that the requested record belongs to the current user or tenant.
OAuth 2.0 is an authorization framework. It allows a client application to obtain limited access to a protected resource, often on behalf of a user. It defines roles such as resource owner, client, authorization server and resource server, along with flows for obtaining access tokens.
OAuth 2.0 does not, by itself, define a universal user identity or sign-in protocol. A successful OAuth authorization does not automatically tell an API everything it needs to know about the user's identity.
OpenID Connect (OIDC) builds an authentication layer on top of OAuth 2.0. It defines the ID token and standardized identity claims, allowing a client to verify information about the authenticated end user. An ID token is intended for the client application; an access token is intended for a resource server.
Do not send an ID token to an API as though it were an access token. The API must validate the correct token type, audience, issuer, signature, expiry and permissions for its own resource.
JSON Web Token (JWT) is a compact format for representing claims. JWTs are commonly used as access tokens, but OAuth 2.0 does not require access tokens to be JWTs. Some providers issue opaque tokens that the resource server must validate through introspection.
A JWT is not automatically encrypted. A signed token's header and payload are normally readable by anyone who obtains it. Do not put passwords, private keys, recovery codes or sensitive personal information in a JWT payload. Signing protects integrity; it does not make the claims confidential.
A JWT commonly contains three Base64URL-encoded sections separated by periods:
A typical request flow looks like this:
User
|
v
Client Application
|
| 1. Sign in through an identity provider
v
Authorization Server / OpenID Provider
|
| 2. Issues an access token
v
Client Application
|
| 3. Authorization: Bearer <access-token>
v
FastAPI Resource Server
|
| 4. Verify signature, issuer, audience, expiry and claims
| 5. Check user, tenant and permission rules
v
Protected API Resource
The API should reject a token if its signature is invalid, its lifetime has ended, its issuer is unexpected, its audience does not identify the API, or required claims are missing. Even a cryptographically valid token can be inappropriate for a particular endpoint if it lacks the required scope or the user no longer has access to the requested resource.
| Claim | Purpose | Security consideration |
|---|---|---|
| sub | Subject represented by the token | Use a stable, unique identifier |
| iss | Issuer that created the token | Compare against a trusted issuer exactly |
| aud | Intended recipient or resource | Reject tokens issued for a different API |
| exp | Expiration time | Enforce a short access-token lifetime |
| nbf | Time before which the token is not valid | Reject tokens used too early |
| iat | Time the token was issued | Useful for policy and audit checks |
| jti | Unique token identifier | Can support revocation or replay controls |
| scope | Granted permissions | Enforce the permissions required by each route |
A JWT's claims are statements made by its issuer. The API must trust the issuer and validate the claims before using them. Never treat an arbitrary decoded payload as proof of identity.
Selecting the correct flow is one of the most important design decisions in an authentication system. The flow must match the type of client, the trust boundaries and the identity provider.
For modern user-facing applications, Authorization Code with Proof Key for Code Exchange (PKCE) is the preferred starting point. It is suitable for browser-based applications, native applications and other clients that need a user to sign in through an authorization server.
The client creates a one-time verifier and derives a challenge from it. It sends the challenge during the authorization request. After the user authenticates, the authorization server returns a short-lived authorization code. The client exchanges that code using the original verifier. The authorization server checks the verifier before issuing tokens.
PKCE reduces the risk that an intercepted authorization code can be redeemed by an attacker. Use the S256 challenge method, exact registered redirect URIs, transaction-specific state and the provider's supported protections. In OpenID Connect flows, validate the nonce in the ID token as required by the provider's implementation.
In this architecture, FastAPI is normally the resource server. The client or an identity-provider SDK performs the interactive sign-in flow, and FastAPI validates the access token presented to its endpoints.
The Client Credentials flow is intended for machine-to-machine communication when a service acts on its own behalf rather than on behalf of an end user. A backend worker might use a client credential to call an internal API.
Treat client secrets as high-value credentials. Store them in a secrets manager, rotate them, use the narrowest scopes available and avoid embedding them in browser or mobile application code. Where supported and appropriate, prefer stronger client authentication methods such as private-key JWT or mutual TLS.
Older FastAPI tutorials often demonstrate the OAuth2 password grant, sometimes called Resource Owner Password Credentials (ROPC). In this flow, a client collects the user's username and password and sends them directly to the authorization server to obtain a token.
This approach is no longer recommended for new applications. The OAuth 2.0 Security Best Current Practice, RFC 9700, says the password grant MUST NOT be used. It exposes user credentials to the client and does not support many modern authentication approaches, including multi-step sign-in and federated identity flows.
FastAPI still documents utilities that can demonstrate this older flow and can be useful when maintaining a legacy first-party application. Their presence in the framework does not make the grant suitable for a new public application. If you control the client and API and simply need a local login endpoint, be clear that you are implementing your own first-party authentication system rather than claiming to provide a complete OAuth2 authorization server.
For new applications, use an established OpenID Connect provider with Authorization Code and PKCE. Avoid building an authorization server from scratch unless you have a strong reason and the expertise to operate one securely.
Create a virtual environment and install the packages needed by the examples:
python -m venv .venv
# Linux or macOS
source .venv/bin/activate
# Windows PowerShell
# .venvScriptsActivate.ps1
python -m pip install --upgrade pip
pip install fastapi "uvicorn[standard]" "pyjwt[crypto]" "pwdlib[argon2]" pydantic-settings
The examples use:
The authorization-code flow itself is normally handled by an identity provider and its supported client library. A FastAPI resource server does not need to collect the user's password or implement the provider's token endpoint.
Use maintained dependency versions and commit a lock file so that the same tested dependencies can be installed in development and deployment. PyJWT's 2.14.0 release includes important key-validation hardening, and later 2.15.x releases add further fixes. Use a current patched release rather than copying old version pins from an outdated tutorial. If you use RSA or ECDSA keys, install the cryptography extra as shown above.
Authentication configuration includes secrets and trust relationships. Keep private keys, client secrets, database credentials and signing secrets out of source code. Use environment variables or a dedicated secrets manager, and provide different credentials for development, staging and production.
A simple settings module can look like this:
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(
env_file=".env",
env_file_encoding="utf-8",
extra="ignore",
)
jwt_issuer: str
api_audience: str
jwks_url: str
settings = Settings()
Example environment configuration:
JWT_ISSUER=https://identity.example.com/
API_AUDIENCE=https://api.example.com/
JWKS_URL=https://identity.example.com/.well-known/jwks.json
The issuer, audience, JWKS endpoint and allowed algorithms must come from trusted configuration. Do not accept a JWKS URL, issuer or algorithm from an incoming request or from an unverified JWT header. Otherwise, an attacker may influence where the API retrieves keys or how it attempts to validate a token.
For a production deployment, inject these settings through the platform's environment or secret-management interface. A local .env file should be excluded from version control. Do not print settings objects or environment dumps in logs because they may contain sensitive values.
A resource server receives access tokens and decides whether to serve protected resources. It does not necessarily issue tokens.
This separation is useful because authentication is a specialist security function. An identity provider can manage password resets, passkeys, multi-factor authentication, suspicious sign-in detection, account recovery, consent and federated identity. FastAPI can focus on API-specific authorization, data access and business rules.
A typical production arrangement includes:
If the API accepts opaque access tokens, it may need to call the provider's token-introspection endpoint. If the provider issues JWT access tokens, the API can validate their signature and claims using the provider's published signing keys. Follow the provider's exact access-token validation instructions; different providers use different claims, formats and key-rotation policies.
Many identity providers publish public signing keys through a JSON Web Key Set (JWKS) endpoint. The provider signs tokens using a private key, while resource servers retrieve the corresponding public key to verify signatures. This avoids distributing the signing private key to every API.
The following example uses PyJWT's PyJWKClient to retrieve the public key selected by the token's key identifier. The JWKS URL is configured by the application, not read from the token.
import jwt
from jwt import InvalidTokenError, PyJWKClient
from app.config import settings
jwks_client = PyJWKClient(settings.jwks_url)
def verify_access_token(token: str) -> dict:
signing_key = jwks_client.get_signing_key_from_jwt(token).key
claims = jwt.decode(
token,
signing_key,
algorithms=["RS256"],
issuer=settings.jwt_issuer,
audience=settings.api_audience,
options={
"require": ["exp", "iss", "aud", "sub"],
},
leeway=30,
)
if not isinstance(claims.get("sub"), str) or not claims["sub"]:
raise InvalidTokenError("Token subject is missing")
token_use = claims.get("token_use")
if token_use is not None and token_use != "access":
raise InvalidTokenError("Unexpected token type")
return claims
This is an illustrative integration pattern, not a universal drop-in verifier. Confirm the provider's token profile before enforcing or omitting provider-specific claims such as token_use. Some providers use a different claim name or token format. If the provider uses a different signing algorithm, configure only the exact algorithms that it documents and that your application has deliberately approved.
Important validation rules include:
PyJWT's PyJWKClient can cache retrieved signing keys, but your application must still handle key rotation and JWKS endpoint failures. Keep the endpoint fixed to the trusted provider, use HTTPS, set sensible network timeouts at the infrastructure layer and monitor key-fetch failures. Never allow an arbitrary user-controlled URL to be passed to the JWKS client.
FastAPI dependencies make it possible to validate a bearer token once and reuse the result across protected routes. For an API using an external OAuth2 authorization-code provider, OAuth2AuthorizationCodeBearer can describe the authorization-code flow in the OpenAPI document and extract the bearer token from the Authorization header.
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2AuthorizationCodeBearer
from jwt import InvalidTokenError
oauth2_scheme = OAuth2AuthorizationCodeBearer(
authorizationUrl="https://identity.example.com/authorize",
tokenUrl="https://identity.example.com/oauth/token",
scopes={
"profile:read": "Read the signed-in user's profile",
"orders:read": "Read permitted orders",
"orders:write": "Create or update permitted orders",
},
)
def get_token_claims(token: str = Depends(oauth2_scheme)) -> dict:
try:
return verify_access_token(token)
except InvalidTokenError as exc:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
) from exc
except PyJWKClientConnectionError as exc:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="Authentication provider temporarily unavailable",
) from exc
except PyJWKClientError as exc:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
) from exc
In a real implementation, catch the specific token and key-retrieval exceptions expected from the selected library and map them to safe HTTP responses. Avoid a broad exception handler that hides programming errors or makes an identity-provider outage indistinguishable from an invalid token. Log operational failures with a correlation ID, but never log the bearer token itself.
The authorizationUrl and tokenUrl values in this example describe the provider's authorization-code flow for OpenAPI documentation. They do not make FastAPI an authorization server and do not implement the interactive sign-in process. The client application must use the provider's supported Authorization Code with PKCE integration.
After verifying the token, use the subject claim to load the application user or service account. This allows the API to enforce account status, tenant membership and current application permissions.
from dataclasses import dataclass
from fastapi import Depends, HTTPException, status
@dataclass
class CurrentUser:
user_id: str
tenant_id: str
is_active: bool
def load_user_by_subject(subject: str) -> CurrentUser | None:
# Replace this placeholder with a database repository lookup.
# Match the stable identity-provider subject, not an unverified email.
raise NotImplementedError
def get_current_user(
claims: dict = Depends(get_token_claims),
) -> CurrentUser:
user = load_user_by_subject(claims["sub"])
if user is None or not user.is_active:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid authentication credentials",
headers={"WWW-Authenticate": "Bearer"},
)
return user
The repository function is deliberately left as an application-specific boundary. A production implementation should query a persistent database and handle missing users, disabled accounts and tenant membership consistently. Do not trust a role or tenant identifier from a request body when the authenticated identity and server-side records can determine it.
A route can now require an authenticated user by declaring the dependency:
from fastapi import APIRouter, Depends
router = APIRouter()
@router.get("/users/me")
def read_my_profile(
current_user: CurrentUser = Depends(get_current_user),
):
return {
"user_id": current_user.user_id,
"tenant_id": current_user.tenant_id,
}
Requests without a valid bearer token receive a 401 Unauthorized response. A valid token allows the dependency to resolve the principal, but the route must still enforce any resource-specific permission rules.
OAuth2 scopes represent permissions granted to a client or token. They are useful for expressing what an application may do, but they do not replace domain-level authorization.
For example, an access token may contain profile:read and orders:read scopes. The API can require the relevant scope before running an operation. FastAPI provides SecurityScopes for this purpose.
from fastapi import Depends, HTTPException, Security, status
from fastapi.security import SecurityScopes
def get_current_user_with_scopes(
security_scopes: SecurityScopes,
claims: dict = Depends(get_token_claims),
) -> CurrentUser:
granted = set(str(claims.get("scope", "")).split())
required = set(security_scopes.scopes)
if not required.issubset(granted):
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Not enough permissions",
headers={"WWW-Authenticate": "Bearer"},
)
user = load_user_by_subject(claims["sub"])
if user is None or not user.is_active:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid authentication credentials",
headers={"WWW-Authenticate": "Bearer"},
)
return user
@router.get("/orders")
def list_orders(
current_user: CurrentUser = Security(
get_current_user_with_scopes,
scopes=["orders:read"],
),
):
# Also filter the query by current_user.tenant_id and ownership rules.
return {"message": "Return only orders this user may access"}
The example assumes the provider puts space-delimited scopes in the scope claim. Some providers use a different claim shape. Adapt the extraction logic to the provider's documented access-token format and reject unexpected types rather than silently treating malformed data as an empty permission set.
Scopes are often coarse-grained. A token with orders:read does not mean a user can read every order in the system. The API must still check record ownership, tenant boundaries and business rules. For more detailed API boundary guidance, see API design fundamentals and API design principles with FastAPI.
Some applications maintain a first-party username-and-password database instead of delegating sign-in to an external identity provider. In that case, password storage must be designed carefully. Never store plaintext passwords, reversible password encryption or fast general-purpose hashes such as plain SHA-256.
Password hashing functions are deliberately expensive and use unique salts. Argon2id is a strong modern choice for many applications. The pwdlib package provides a convenient interface for recommended password-hashing configurations.
from pwdlib import PasswordHash
password_hash = PasswordHash.recommended()
def hash_password(plain_password: str) -> str:
return password_hash.hash(plain_password)
def verify_password(
plain_password: str,
stored_hash: str,
) -> bool:
return password_hash.verify(plain_password, stored_hash)
Store only the resulting password hash in the user table. When a user signs in, retrieve the stored hash and use the library's verification method. Do not compare password hashes manually or create your own salt and hashing algorithm.
A production password policy should consider minimum length, breached-password screening, secure password reset, multi-factor authentication and rate limiting. Avoid arbitrary complexity rules that encourage predictable substitutions. Password reset tokens should be random, short-lived, single-use and stored securely. Password changes should invalidate or revoke sessions according to the application's risk model.
If an application delegates authentication to an identity provider, do not duplicate the provider's password database. Store only the application-specific identity mapping and profile data that the API actually needs.
FastAPI's OAuth2PasswordBearer and OAuth2PasswordRequestForm utilities are often shown together in tutorials. They can be useful when maintaining an existing first-party application that already uses the password grant, but RFC 9700 explicitly says the Resource Owner Password Credentials grant must not be used for new OAuth2 deployments.
The form endpoint accepts username and password as form fields, not JSON. The API verifies the submitted password against the stored password hash and returns a token. The following shortened example illustrates the credential check only; it is not a complete authorization server and should not be used as a template for a new third-party sign-in system.
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
@app.post("/legacy/token")
def legacy_token(
form_data: OAuth2PasswordRequestForm = Depends(),
):
user = find_user_by_username(form_data.username)
if user is None or not verify_password(
form_data.password,
user.hashed_password,
):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect username or password",
headers={"WWW-Authenticate": "Bearer"},
)
# Issue only a short-lived access token using a reviewed
# token-creation function and the application's key policy.
return create_legacy_access_token(user)
Do not expose this endpoint as a general-purpose third-party OAuth2 login service. Do not let an untrusted client collect credentials for another identity provider. Plan a migration to Authorization Code with PKCE or a suitable OIDC provider when modernizing an existing system.
Some internal systems legitimately issue their own JWTs. In that case, the API or a dedicated authentication service must protect the signing key and define a strict token profile. The example below demonstrates the essential claims for an access token signed with HS256. It assumes a strong secret supplied through a secrets manager and a single trusted service responsible for both signing and verification.
from datetime import datetime, timedelta, timezone
import jwt
def create_access_token(
subject: str,
secret_key: str,
issuer: str,
audience: str,
) -> str:
now = datetime.now(timezone.utc)
payload = {
"sub": subject,
"iss": issuer,
"aud": audience,
"iat": now,
"nbf": now,
"exp": now + timedelta(minutes=10),
"jti": create_unique_token_id(),
"token_use": "access",
}
return jwt.encode(
payload,
secret_key,
algorithm="HS256",
)
The helper create_unique_token_id represents a cryptographically random unique identifier generated by the application. It is not a fixed value or a user-controlled string. In a real system, implement it using a secure random UUID or token identifier.
For a small single-service application, a high-entropy symmetric key may be operationally simple. In a multi-service architecture, asymmetric signing can be preferable: the issuer holds the private key and resource servers receive only public keys. This reduces the number of components that can mint tokens. Protect private keys, rotate keys using a planned key identifier strategy, and keep the algorithm allow-list fixed in verifier configuration.
JWTs are normally difficult to revoke before their expiration unless the system adds state. Keep access tokens short-lived and choose a revocation strategy based on the application's risk. A token version, denylist keyed by jti, introspection endpoint or centralized session service may be appropriate in different systems. Each approach has operational and consistency trade-offs.
Access tokens should generally be short-lived and limited to the intended API and permissions. A stolen access token can be replayed by whoever possesses it until it expires or is otherwise rejected. Avoid unnecessarily long token lifetimes.
Refresh tokens are higher-value credentials because they can obtain new access tokens. If your identity provider issues refresh tokens, follow its storage, rotation and revocation guidance. For public clients, RFC 9700 requires refresh-token replay protection through sender-constrained refresh tokens or refresh-token rotation.
For a first-party application that manages its own refresh tokens, consider storing only a cryptographic hash of each opaque refresh token in the database. Associate it with a user, client, session, scope and expiry. When a refresh token is used, invalidate it and issue a replacement in the same transaction. If an already-used token appears again, treat it as a possible replay event and revoke the related token family or session according to the policy.
Logout is not automatically achieved by deleting a JWT from the browser. If the token remains valid, a copied version may still be accepted. A client should discard its local credential, and the server or identity provider should revoke refresh tokens or sessions where supported. Short access-token lifetimes reduce the residual window. For high-risk applications, use server-side session state or a token revocation mechanism.
Do not store bearer tokens in URLs. URLs can be recorded in browser history, server logs, analytics and referrer headers. Browser applications should follow the identity provider's recommended storage model, protect against cross-site scripting and use secure cookie attributes when cookies are part of the design. Mobile and desktop clients should use platform-provided secure storage.
Role-Based Access Control (RBAC) assigns permissions through roles such as member, editor, support agent and administrator. It can simplify broad access policies, but role checks alone are not enough for many APIs.
A route might require an administrator role, while a separate rule ensures that the administrator belongs to the same tenant as the requested record. A customer may read an order only if the order belongs to that customer. A support agent may access a record only when a valid support workflow permits it.
A robust authorization decision may combine:
Avoid trusting role names supplied in request bodies or query parameters. If roles are included in a token, consider how quickly changes must take effect. A user whose privileges were revoked may retain an old role claim until the token expires. High-risk permission changes may require short token lifetimes, a current database check or centralized policy evaluation.
For a practical example of role-based access control in a larger FastAPI application, see the hospital management system API project.
Authentication code is security-sensitive. A small configuration mistake can undermine the entire system.
A JWT decoder may expose a payload without proving that the token was signed by a trusted issuer. Never treat an unverified decode as authentication. Use a maintained JWT library and verify the signature with the correct key and fixed algorithm policy.
Do not build the allowed algorithm list from the incoming token header. Configure the exact algorithms expected from the issuer. Do not mix symmetric and asymmetric algorithms casually or reuse public-key material as an HMAC secret. Keep PyJWT current and review its security advisories.
A valid token issued for another service should not be accepted by your API. Validate both issuer and audience against trusted configuration. This helps prevent token substitution across applications and environments.
ID tokens communicate authentication information to the client. Access tokens authorize access to a resource server. Validate the token type and audience expected by your API. Do not assume that any JWT from the same identity provider is valid for every purpose.
A database breach should not reveal usable passwords. Use a modern password-hashing algorithm such as Argon2id with unique salts and appropriate parameters. Keep the hashing library maintained and use its verification method.
Long-lived bearer tokens increase the time available for an attacker to replay a stolen credential. Prefer short-lived access tokens and a carefully designed refresh-token process. Do not issue refresh tokens to clients that do not need them.
A user who is authenticated and has a broad read scope may still not be allowed to access a specific record. Check ownership and tenant boundaries on the server for every relevant operation. This is a major API security concern.
Never commit signing keys, client secrets or database passwords. Do not log Authorization headers or raw tokens. Return generic authentication errors to clients while keeping structured, redacted diagnostic information in protected logs.
Cross-Origin Resource Sharing controls whether browser scripts from one origin can read responses from another origin. It does not stop curl, mobile clients or malicious non-browser requests from calling an API. CORS is not a substitute for authentication, authorization or CSRF protection.
Login, password reset, verification and token endpoints are attractive targets for brute-force attempts and automated abuse. Apply rate limits, monitor repeated failures, use progressive controls where appropriate and avoid revealing whether a username or email exists.
OAuth redirect URIs must be registered and compared exactly, subject only to the narrowly defined exceptions for native applications. Do not redirect users to arbitrary URLs supplied in query parameters. Open redirects can expose authorization codes or tokens.
The OWASP API Security Top 10 is a useful starting point for reviewing API risks. The OAuth 2.0 Security Best Current Practice, RFC 9700 provides current guidance for OAuth clients and authorization servers.
Authentication should be tested as a security boundary, not only as a happy-path feature. Tests should verify that protected endpoints reject missing, malformed, expired, incorrectly signed and incorrectly scoped credentials.
FastAPI's TestClient can exercise routes without starting a production server. A simplified test for an endpoint that requires authentication might look like this:
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_profile_requires_authentication():
response = client.get("/users/me")
assert response.status_code == 401
def test_profile_accepts_valid_access_token():
token = create_test_access_token_for_user("user-123")
response = client.get(
"/users/me",
headers={"Authorization": f"Bearer {token}"},
)
assert response.status_code == 200
The helper create_test_access_token_for_user should use a test-only signing key and the same issuer, audience and required claims as the application verifier. Do not use production signing keys in tests. If the application validates tokens through an external JWKS endpoint, mock the trusted key client or use a local test identity provider so tests remain deterministic.
A useful authentication test matrix includes:
| Scenario | Expected result |
|---|---|
| No Authorization header | 401 Unauthorized |
| Malformed bearer token | 401 Unauthorized |
| Invalid signature | 401 Unauthorized |
| Expired token | 401 Unauthorized |
| Wrong issuer | 401 Unauthorized |
| Wrong audience | 401 Unauthorized |
| Missing required claim | 401 Unauthorized |
| Disabled or unknown user | 401 or the documented account policy |
| Valid token without required scope | 403 Forbidden |
| Valid token accessing another tenant's record | 403 or 404 according to the disclosure policy |
| Valid token with required permission and ownership | Successful response |
Also test password hashing and verification, account lockout or rate-limiting behaviour, refresh-token rotation, logout, key rotation and the handling of identity-provider outages. Integration tests should verify the actual database and security dependencies. Contract tests can verify that the identity provider's access-token format still matches the API's assumptions.
Do not write tests that only assert that a token can be decoded. Test that the API rejects a token when any required trust condition is violated.
Start the development server with Uvicorn:
uvicorn app.main:app --reload
The interactive API documentation is normally available at /docs, and the generated OpenAPI document is available at /openapi.json. When an OAuth2 security scheme is configured correctly, the documentation can display the authorization flow and scopes.
Interactive documentation is useful for development and testing, but production documentation should not expose internal implementation details or sensitive endpoints unnecessarily. If the API is public, describe authentication requirements, scopes, error responses and token expectations clearly. If the API is private, restrict documentation access according to the deployment's security policy.
For guidance on documenting API contracts, see Swagger and OpenAPI documentation standards. For deployment and runtime packaging, see Dockerizing a FastAPI application.
A local authentication example is not production-ready until its deployment environment is configured safely.
Credentials and bearer tokens must be protected in transit. Terminate TLS at a trusted load balancer or platform edge, and ensure internal service communication follows the deployment's security requirements. Do not send tokens over plain HTTP outside local development.
Use the hosting platform's environment variables or a secrets manager. Restrict access to production secrets, rotate them deliberately and avoid printing them in build logs. If using asymmetric signing, keep private keys only in the issuer's protected environment and distribute public keys through a trusted JWKS endpoint.
List only the browser origins that should be permitted. Specify the required methods and headers. If cookies are used, configure credentials deliberately and do not combine credentialed requests with a wildcard origin. Remember that CORS is not an access-control mechanism for the API itself.
Protect login, registration, password reset, verification, refresh and other sensitive routes. Use limits that account for the application architecture and avoid relying exclusively on in-memory counters when the API runs across multiple instances.
Record authentication successes and failures, token-validation errors, permission denials, unusual refresh activity and administrative changes. Do not record passwords, raw tokens, authorization headers or private keys. Use request identifiers to connect events without exposing credentials.
The API must handle signing-key changes without accepting untrusted keys. Use the provider's documented JWKS rotation process and keep key retrieval bounded and observable. Decide how the application behaves when the identity provider or JWKS endpoint is temporarily unavailable. For protected resources, failing closed is generally safer than accepting unverifiable tokens.
Authentication packages are part of the application's security perimeter. Pin tested versions, review release notes and security advisories, run dependency scanning and update promptly when a security fix applies. Do not assume that a package is safe simply because it is widely used or because an old tutorial recommended it.
For broader API threat assessment, read the complete guide to API vulnerability assessment.
JWTs are not automatically better than sessions. They solve different operational problems, and either can be appropriate depending on the application.
| Consideration | JWT access tokens | Server-side sessions |
|---|---|---|
| State | Claims are carried in the token | Session state is stored server-side |
| Revocation | Requires expiry, denylist, introspection or related controls | Often straightforward by deleting or invalidating the session |
| Scaling | Verification can be local when keys and claims are available | Requires shared session storage or routing strategy |
| Payload | Claims may be readable by token holders | Session data remains on the server |
| Best fit | Distributed APIs and delegated authorization | Traditional web apps and applications needing immediate session control |
JWTs can reduce repeated session lookups, but they introduce key management, claim validation, token lifecycle and revocation considerations. A server-side session can be easier to revoke and may be a better choice for a browser application that does not need a stateless token architecture.
Choose based on the threat model, client type, infrastructure and operational requirements. Avoid choosing JWT merely because it is popular.
Before releasing an authenticated API, review the following:
The following documentation and standards provide the authoritative details behind the implementation choices in this guide:
JWT is a token format for representing claims. OAuth2 is an authorization framework that defines how clients obtain access to protected resources. OAuth2 access tokens may be JWTs or opaque strings. They solve related but different problems.
FastAPI provides the dependency injection, security utilities and OpenAPI integration needed to implement JWT bearer authentication. It does not automatically issue tokens or create a complete identity provider. Developers must integrate a trusted identity provider or implement and operate the required token-issuing system themselves.
Not necessarily. A typical signed JWT has a readable header and payload. Its signature protects integrity and authenticity, not confidentiality. Avoid placing secrets or sensitive personal information in ordinary JWT claims.
OAuth2PasswordBearer is a FastAPI security dependency that extracts a bearer token from the Authorization header and describes an OAuth2 password flow in the generated OpenAPI schema. It does not validate the JWT by itself, create an authorization server or make an application compliant with every OAuth2 security requirement.
No. RFC 9700 says the Resource Owner Password Credentials grant must not be used. New applications should normally use an established OpenID Connect provider and Authorization Code with PKCE. Older password-flow examples may still be relevant when maintaining a legacy first-party application.
An access token is presented to a resource server to obtain access to an API. An ID token is an OpenID Connect credential intended for the client application and contains authentication information about the user. Do not substitute one for the other.
There is no universal lifetime. Many applications use a short access-token lifetime, often around five to fifteen minutes, and rely on a carefully protected refresh-token or session mechanism for continuity. The correct duration depends on the sensitivity of the API, client type and revocation requirements.
Storage depends on the client architecture. Browser applications must consider cross-site scripting, cross-site request forgery and cookie protections. Native applications should use platform secure storage. Never place tokens in URLs or commit them to source control. Follow the identity provider's recommended architecture rather than copying a storage pattern without understanding its risks.
A FastAPI dependency can extract the bearer token, use a trusted JWT library to verify the signature and required claims, resolve the subject to a current user and then enforce authorization rules. Signature verification alone is not enough: issuer, audience, expiry, token purpose and permissions must also be checked.
The API should reject an expired access token, normally with 401 Unauthorized. The client may obtain a new access token through the identity provider's supported session or refresh process. It should not keep using an expired token or extend its expiry locally.
A self-contained JWT does not automatically know that it has been revoked. Systems can use short lifetimes, token deny-lists, token-version checks, introspection or session state to support earlier revocation. Refresh-token revocation should also be considered.
401 Unauthorized means the request lacks valid authentication credentials or the credentials cannot be accepted. 403 Forbidden means the request is understood but the authenticated principal is not permitted to perform the operation. Some applications return 404 instead of 403 for resources whose existence should not be disclosed.
No. CORS controls browser access to cross-origin responses. It does not authenticate callers or prevent requests from non-browser clients. Every protected API operation still needs server-side authentication and authorization.
For most applications that need user sign-in, an established OpenID Connect provider is safer and more maintainable. It can handle identity lifecycle, multi-factor authentication, recovery and protocol details. A service may issue its own tokens for a well-defined internal use case, but then it owns key management, token validation, revocation and security operations.
Secure FastAPI authentication requires more than generating a JWT and checking its signature. A reliable system distinguishes authentication from authorization, uses the correct OAuth2 or OpenID Connect flow, validates tokens against a trusted issuer and enforces application-specific permissions on every protected resource.
For modern user-facing applications, Authorization Code with PKCE through a trusted identity provider is the recommended approach. FastAPI can act as a resource server by validating access tokens, resolving users and applying scopes, roles, tenant boundaries and ownership rules. If an application manages its own passwords, it must also use modern password hashing, secure recovery workflows and appropriate abuse controls.
JWTs can be useful, but they are not a universal replacement for server-side sessions. Choose the approach that fits the application and threat model, keep access tokens short-lived, protect refresh credentials, test failure cases and keep dependencies patched. The objective is not simply to make an endpoint require a token; it is to ensure that every request is authenticated, authorized and handled safely throughout the application's lifecycle.

Learn practical API design with FastAPI, from REST resources and Pydantic validation to authentication, pagination, versioning, testing, performance, security, and production deployment.
Read
A production-style FastAPI REST API for hospital management featuring JWT authentication, role-based access control, PostgreSQL, Docker, and secure healthcare workflows.
Read
A practical SQLAlchemy 2.0 guide to Python ORM architecture, typed models, sessions, transactions, relationships, FastAPI integration, async database access, migrations, and production performance.
Read