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:

  1. Include it in the Authorization header of subsequent requests:
    Authorization: JWT <access_token>
    
  2. 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.