JWT Tokens

Overview

ServITech uses JWT (JSON Web Tokens) for stateless authentication. Tokens are generated upon successful login and must be included in the Authorization header for protected endpoints.

Token Generation

When you successfully authenticate via the /auth/login endpoint, the API returns:

{
  "success": true,
  "message": "User logged in successfully",
  "data": {
    "user": {
      "id": 1,
      "role": "USER",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expires_in": 3600
  }
}

token

string

required

The JWT access token for authentication

expires_in

integer

required

Token lifetime in seconds (default: 3600 seconds = 1 hour)

Token Structure

JWT tokens consist of three parts separated by dots:

header.payload.signature

Contains token type and signing algorithm:

{
  "typ": "JWT",
  "alg": "HS256"
}

Payload

Contains user claims and metadata:

{
  "iss": "https://api.servitech.com",
  "iat": 1709913600,
  "exp": 1709917200,
  "nbf": 1709913600,
  "jti": "a7b3c9d1e5f2",
  "sub": 1,
  "prv": "87e0af1e..."
}

iss

string

Issuer - The API that issued the token

iat

integer

Issued At - Unix timestamp when token was created

exp

integer

Expiration - Unix timestamp when token expires

nbf

integer

Not Before - Token is not valid before this timestamp

sub

integer

Subject - The user ID the token belongs to

jti

string

JWT ID - Unique identifier for this token

Signature

Created using the header, payload, and secret key defined in JWT_SECRET environment variable.

Token Configuration

Configuration is managed in config/jwt.php:

Setting	Environment Variable	Default	Description
Time to Live (TTL)	`JWT_TTL`	60 minutes	Token expiration time
Refresh TTL	`JWT_REFRESH_TTL`	20160 minutes (2 weeks)	Refresh window after expiration
Algorithm	`JWT_ALGO`	HS256	Signing algorithm
Blacklist Enabled	`JWT_BLACKLIST_ENABLED`	true	Enable token blacklisting on logout
Leeway	`JWT_LEEWAY`	0 seconds	Clock skew tolerance
Secret	`JWT_SECRET`	-	Secret key for signing (required)

Never expose your JWT_SECRET in client-side code or public repositories. Keep it secure in your .env file.

Using Tokens

Include the JWT token in the Authorization header with the Bearer scheme:

curl -X GET "https://api.servitech.com/user/profile" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Accept: application/json"

Token Storage

Web Applications

For web applications, store tokens securely: Recommended approaches:

HttpOnly Cookies (most secure)
- Not accessible via JavaScript
- Automatic inclusion in requests
- Protected from XSS attacks
Memory/State Management (e.g., Redux, Vuex)
- Token lost on page refresh
- Requires re-authentication
- Safe from XSS if properly implemented

Not recommended:

❌ localStorage (vulnerable to XSS attacks)
❌ sessionStorage (vulnerable to XSS attacks)

Mobile Applications

For mobile apps:

iOS: Use Keychain Services
Android: Use EncryptedSharedPreferences
React Native: Use react-native-keychain or expo-secure-store

Token Expiration

Tokens expire after the configured TTL (default: 60 minutes).

Handling Expired Tokens

When a token expires, the API returns:

{
  "success": false,
  "message": "Token has expired",
  "errors": {}
}

HTTP Status: 401 Unauthorized

Token Refresh

While the current implementation doesn’t expose a dedicated refresh endpoint, you can:

Re-authenticate - Use the /auth/login endpoint to get a new token
Implement refresh logic - Request a new token before expiration

The refresh window (JWT_REFRESH_TTL) is 2 weeks by default. This setting is primarily for internal package behavior.

Token Blacklisting

When a user logs out via /auth/logout, the token is added to a blacklist:

Blacklist Enabled: JWT_BLACKLIST_ENABLED=true (default)
Grace Period: JWT_BLACKLIST_GRACE_PERIOD=0 seconds (default)

Blacklisted tokens cannot be used for authentication, even if they haven’t expired.

Database Storage

Blacklisted tokens are stored in the database (via the configured storage provider) and checked on each authenticated request.

Security Best Practices

Always use HTTPS

Never transmit tokens over unencrypted HTTP connections. Always use HTTPS in production to prevent token interception.

Implement token expiration

Use reasonable TTL values (30-60 minutes recommended). Shorter lifetimes reduce the window for token abuse.

Validate tokens on every request

The API automatically validates tokens using the auth:api middleware. Never skip this validation.

Rotate secrets regularly

Periodically rotate your JWT_SECRET and invalidate all existing tokens by requiring re-authentication.

Monitor for suspicious activity

Log authentication events and monitor for unusual patterns (e.g., tokens used from multiple IPs).

Error Handling

Common JWT-related errors:

Error	HTTP Status	Description	Solution
Token has expired	401	Token TTL exceeded	Re-authenticate to get a new token
Token invalid	401	Malformed or tampered token	Verify token format and signature
Token not found	401	No Authorization header	Include token in request header
Token blacklisted	401	Token was invalidated via logout	Re-authenticate to get a new token

Login

Get a JWT token by logging in

Logout

Invalidate your token

Get Started

Authentication

Core Concepts

Overview

Token Generation

Token Structure

Header

Payload

Signature

Token Configuration

Using Tokens

Token Storage

Web Applications

Mobile Applications

Token Expiration

Handling Expired Tokens

Token Refresh

Token Blacklisting

Database Storage

Security Best Practices

Error Handling

Login

Logout

Build docs developers (and LLMs) love

Get Started

Authentication

Core Concepts

​Overview

​Token Generation

​Token Structure

​Header

​Payload

​Signature

​Token Configuration

​Using Tokens

​Token Storage

​Web Applications

​Mobile Applications

​Token Expiration

​Handling Expired Tokens

​Token Refresh

​Token Blacklisting

​Database Storage

​Security Best Practices

​Error Handling

​Related Resources

Login

Logout

Build docs developers (and LLMs) love

Overview

Token Generation

Token Structure

Header

Payload

Signature

Token Configuration

Using Tokens

Token Storage

Web Applications

Mobile Applications

Token Expiration

Handling Expired Tokens

Token Refresh

Token Blacklisting

Database Storage

Security Best Practices

Error Handling

Related Resources