Overview
The Security class extends Depends to handle authentication and authorization with support for OAuth2 scopes. It allows you to declare security requirements for your endpoints and automatically validates scopes.
Signature
from fastapi import Security
@dataclass(frozen=True)
class Security(Depends):
dependency: Callable[..., Any] | None = None
use_cache: bool = True
scope: Literal["function", "request"] | None = None
scopes: Sequence[str] | None = None
Parameters
dependency
Callable[..., Any] | None
default:"None"
The security scheme callable (e.g., OAuth2PasswordBearer, HTTPBearer, APIKeyHeader). This dependency should return security credentials that can be validated.
Whether to cache the result of the security dependency within the same request. When True, authentication is performed once per request even if used in multiple dependencies.
scope
Literal['function', 'request'] | None
default:"None"
The scope in which the security dependency operates. Inherited from Depends.
scopes
Sequence[str] | None
default:"None"
A list of OAuth2 scopes required for this endpoint. These scopes will be validated against the scopes provided in the security credentials. If the required scopes are not present, FastAPI will return a 403 Forbidden response.
Usage
Basic Authentication
from fastapi import FastAPI, Security
from fastapi.security import HTTPBearer
app = FastAPI()
security = HTTPBearer()
@app.get("/protected/")
def read_protected(credentials = Security(security)):
return {"token": credentials.credentials}
OAuth2 with Scopes
from fastapi import FastAPI, Security, HTTPException
from fastapi.security import OAuth2PasswordBearer, SecurityScopes
app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(
tokenUrl="token",
scopes={
"read:items": "Read items",
"write:items": "Write items",
},
)
def get_current_user(security_scopes: SecurityScopes, token: str = Security(oauth2_scheme)):
# Validate token and check scopes
# This is a simplified example
token_scopes = ["read:items"] # Extract from token
for scope in security_scopes.scopes:
if scope not in token_scopes:
raise HTTPException(
status_code=403,
detail="Not enough permissions",
)
return {"username": "johndoe", "scopes": token_scopes}
@app.get("/items/")
def read_items(
current_user = Security(get_current_user, scopes=["read:items"])
):
return {"items": ["item1", "item2"], "user": current_user}
@app.post("/items/")
def create_item(
current_user = Security(get_current_user, scopes=["write:items"])
):
return {"message": "Item created", "user": current_user}
Multiple Scopes
from fastapi import FastAPI, Security
from fastapi.security import OAuth2PasswordBearer
app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(
tokenUrl="token",
scopes={
"users:read": "Read users",
"users:write": "Write users",
"admin": "Admin access",
},
)
def get_current_user(token: str = Security(oauth2_scheme)):
# Verify token and return user
return {"username": "johndoe"}
@app.delete("/users/{user_id}")
def delete_user(
user_id: int,
current_user = Security(get_current_user, scopes=["users:write", "admin"])
):
# This endpoint requires both 'users:write' AND 'admin' scopes
return {"message": f"User {user_id} deleted"}
API Key Security
from fastapi import FastAPI, Security, HTTPException
from fastapi.security import APIKeyHeader
app = FastAPI()
api_key_header = APIKeyHeader(name="X-API-Key")
def verify_api_key(api_key: str = Security(api_key_header)):
if api_key != "secret-api-key":
raise HTTPException(status_code=403, detail="Invalid API Key")
return api_key
@app.get("/secure-data/")
def get_secure_data(api_key: str = Security(verify_api_key)):
return {"data": "sensitive information"}
Available Security Schemes
FastAPI provides several built-in security schemes that can be used with Security:
OAuth2PasswordBearer - OAuth2 with password flowOAuth2AuthorizationCodeBearer - OAuth2 with authorization code flowHTTPBasic - HTTP Basic authenticationHTTPBearer - HTTP Bearer token authenticationHTTPDigest - HTTP Digest authenticationAPIKeyQuery - API key in query parametersAPIKeyHeader - API key in request headersAPIKeyCookie - API key in cookiesOpenIdConnect - OpenID Connect authentication
SecurityScopes
The SecurityScopes class is automatically injected when you use scopes with Security. It provides access to the required scopes:
from fastapi.security import SecurityScopes
def get_current_user(security_scopes: SecurityScopes, token: str = Security(oauth2_scheme)):
# security_scopes.scopes contains the list of required scopes
# security_scopes.scope_str contains space-separated scopes string
print(f"Required scopes: {security_scopes.scopes}")
# Validate token and scopes...
See Also