API Reference – Authentication Endpoint (POST /auth)
Section Index
- Overview
- Configuration & Dependencies
- Endpoint Details
- Request
- Response
- Error Responses
- Authentication Flow Diagram
- Usage in Protected Routes
Overview
The POST /auth endpoint is provided by Flask-JWT’s built-in mechanism to authenticate users and issue JSON Web Tokens (JWTs). Clients exchange valid credentials for an access_token, which is then used to access protected resources throughout the API.
Configuration & Dependencies
| Component | Location | Responsibility |
|---|---|---|
| Flask App & JWT Setup | app.py |
Registers /auth, sets secret_key, initializes JWT |
| Credential Verification | security.py |
Defines authenticate and identity functions |
| User Model | models/user.py |
Persists and queries user records |
| Password Safety | werkzeug.security.safe_str_cmp |
Secure string comparison to prevent timing attacks |
Key Configuration in app.py:
from flask import Flask
from flask_restful import Api
from flask_jwt import JWT
from security import authenticate, identity
app = Flask(__name__)
app.secret_key = 'SapanCrackle' # Used to sign JWT tokens
api = Api(app)
# Registers /auth, wired to security.authenticate & security.identity
jwt = JWT(app, authenticate, identity) # /auth endpoint created here
Credential Handlers in security.py:
from werkzeug.security import safe_str_cmp
from models.user import UserModel
def authenticate(username, password):
user = UserModel.find_by_username(username)
if user and safe_str_cmp(user.password, password):
return user
def identity(payload):
user_id = payload['identity']
return UserModel.find_by_id(user_id)
authenticate: Verifies credentials against the database.identity: Retrieves user by ID embedded in JWT payload.
Endpoint Details
{
"title": "Authenticate User",
"description": "Exchange valid username and password for a JWT access token",
"method": "POST",
"baseUrl": "https://api.example.com",
"endpoint": "/auth",
"headers": [
{ "key": "Content-Type", "value": "application/json", "required": true }
],
"bodyType": "json",
"requestBody": "{\n \"username\": \"sapan\",\n \"password\": \"sapan1234\"\n}",
"responses": {
"200": {
"description": "Authentication successful; returns access token",
"body": "{\n \"access_token\": \"<JWT Token>\"\n}"
},
"401": {
"description": "Invalid credentials or missing fields",
"body": "{\n \"message\": \"Invalid credentials\"\n}"
}
}
}
Request
| Field | Type | Required | Description |
|---|---|---|---|
| username | string | yes | Registered user’s name |
| password | string | yes | Corresponding password |
Example:
{
"username": "sapan",
"password": "sapan1234"
}
Successful Response (200)
| Field | Type | Description |
|---|---|---|
| access_token | string | JWT used for protected routes |
Example:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJh..."
}
Error Responses
| Status | Body | Cause |
|---|---|---|
| 401 | { "message": "Invalid credentials" } |
Wrong username or password |
| 400 | { "message": "Bad request" } (default) |
Missing JSON body or fields |
Authentication Flow
Below is a high-level sequence diagram illustrating the steps taken when a client calls POST /auth:
sequenceDiagram
participant Client
participant Server
participant Flask_JWT
participant DB
Client->>Server: POST /auth { username, password }
Server->>Flask_JWT: authenticate(username, password)
Flask_JWT->>Server: call security.authenticate
security.authenticate->>DB: UserModel.find_by_username(username)
DB-->>security.authenticate: user record (or None)
security.authenticate-->>Flask_JWT: user object (or None)
alt valid credentials
Flask_JWT->>Server: generate JWT token
Server-->>Client: 200 { access_token }
else invalid credentials
Server-->>Client: 401 { message: "Invalid credentials" }
end
Usage in Protected Routes
Once an access_token is obtained:
- Include it in the
Authorizationheader of subsequent requests:Authorization: JWT <access_token> - Endpoints decorated with
@jwt_required()(e.g.,GET /book/<title>) will validate the token before granting access .
By centralizing authentication via POST /auth, the API ensures a consistent and secure mechanism for user validation and token issuance.