Skip to content

Authentication

The Tracker API uses JWT (JSON Web Tokens) for authentication. This page explains how to authenticate with the API and manage user access.

Authentication Flow

  1. Client sends credentials (email and password) to the /api/v1/auth/login endpoint
  2. Server validates credentials and returns an access token in the response body and sets a refresh token as an HttpOnly cookie
  3. Client includes the access token in the Authorization header for subsequent requests
  4. Server validates the token and processes the request if the token is valid
  5. When the access token expires, client can use the refresh token cookie to obtain a new access token without re-authentication

Endpoints

Login

POST /api/v1/auth/login

Authenticates a user and returns a JWT token.

Request Body

{
  "username": "user@example.com",
  "password": "password123"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

The refresh token is set as an HttpOnly cookie and is not included in the response body.

JSON Login

POST /api/v1/auth/login/json

Alternative login endpoint that accepts JSON directly.

Request Body

{
  "email": "user@example.com",
  "password": "password123"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "user@example.com",
    "roles": ["admin"],
    "client_list": [1, 2, 3],
    "notification_preferences": {
      "email": false,
      "ui": true
    }
  }
}

The refresh token is set as an HttpOnly cookie and is not included in the response body.

Refresh Token (Using Request Body)

POST /api/v1/auth/refresh

Refreshes an expired access token using a refresh token provided in the request body.

Request Body

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

GET /api/v1/auth/refresh-cookie

Refreshes an expired access token using the refresh token stored in an HttpOnly cookie.

Request

No request body is needed as the refresh token is read from the cookie.

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Using the Token

Once you have obtained a token, include it in the Authorization header of your requests:

GET /api/v1/users/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Role-Based Access Control

The API implements role-based access control (RBAC) to restrict access to certain endpoints based on user roles.

Available Roles

  • admin: Full access to all endpoints
  • user: Access to endpoints based on client_list

Client-Based Access Control

Users are associated with specific clients through the client_list field. This restricts their access to data related to those clients only.

For example, a user with client_list = [1, 2] can only access data for clients with IDs 1 and 2, and their associated brands, production runs, and trackers.

Logout

POST /api/v1/auth/logout

Logs out the user by clearing the refresh token cookie.

Request

No request body is needed.

Response

{
  "detail": "Successfully logged out"
}

Token Expiration

The API uses two types of tokens with different expiration times:

  • Access tokens: Short-lived tokens (default: 30 minutes) used for API requests
  • Refresh tokens: Long-lived tokens (default: 7 days) stored as HttpOnly cookies and used only to obtain new access tokens

When an access token expires, the client can use the refresh token cookie to obtain a new access token without requiring the user to log in again.

Security Considerations

  • Always use HTTPS in production to protect credentials and tokens
  • Access tokens are stored in localStorage for easy access in the frontend
  • Refresh tokens are stored as HttpOnly cookies to prevent access by JavaScript, protecting against XSS attacks
  • The secure flag is set on cookies in non-development environments to ensure they are only sent over HTTPS
  • The samesite attribute is set to "lax" to provide some protection against CSRF attacks
  • Consider using shorter token expiration times for sensitive operations
  • The logout endpoint properly clears the refresh token cookie

JWT Security Hardening

The JWT implementation includes several security enhancements:

  1. Algorithm Validation:
  2. Explicit rejection of the 'none' algorithm
  3. Verification that the algorithm in the token header matches the expected algorithm (HS256)

  4. Prevents algorithm confusion attacks

  5. Comprehensive Claims:

  6. Each token includes standard JWT claims: sub, exp, iat, iss, aud, jti
  7. Custom token_type claim to distinguish between access and refresh tokens

  8. All claims are validated during token verification

  9. Token Uniqueness:

  10. Each token has a unique identifier (JTI claim)
  11. Helps prevent token replay attacks

  12. Enables future token revocation capabilities

  13. Strict Verification Options:

  14. Signature verification is enforced
  15. Expiration time is required and verified
  16. Issuer and audience claims are verified
  17. Prevents token tampering and misuse