Skip to main content

​
Overview

This page documents endpoints for managing authentication tokens and retrieving the current authenticated user’s information.

​
Refresh Access Token

Refresh an expired access token using a valid refresh token. This endpoint returns new access and refresh tokens.

​
Request Body

​
refresh_token
string
required
Valid refresh token obtained from the login endpoint.

​
Response

​
access_token
string
New JWT access token for API requests.
​
refresh_token
string
New refresh token. The old refresh token is automatically revoked.
​
token_type
string
Token type. Always "bearer".
​
expires_in
integer
Access token expiration time in seconds (default: 1800).

​
Example Request

curl -X POST https://api.example.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "7x9kP3mN8qR2wV5tY1uZ4jH6fL0sA3bC"
  }'

​
Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "2aB5cD8eF1gH4jK7lM0nP3qR6sT9uV2w",
  "token_type": "bearer",
  "expires_in": 1800
}

​
Error Responses

​
401 Unauthorized

Returned when the refresh token is invalid, expired, or revoked. 
{
  "detail": "Invalid or expired refresh token"
}

​
500 Internal Server Error

{
  "detail": "Failed to refresh token"
}

​
Token Rotation

When you refresh your tokens:
  1. The old refresh token is immediately revoked
  2. A new access token is generated (expires in 30 minutes)
  3. A new refresh token is generated (expires in 7 days)
  4. Device information and IP address are updated
This token rotation strategy enhances security by limiting the lifetime of refresh tokens.

​
Get Current User

Retrieve information about the currently authenticated user. Requires a valid access token.

​
Headers

​
Authorization
string
required
Bearer token with valid access token.Format: Bearer <access_token>

​
Response

​
id
UUID
Unique identifier for the user.
​
email
string
User’s email address.
​
full_name
string
User’s full name.
​
is_active
boolean
Whether the user account is active.
​
is_verified
boolean
Whether the user’s email has been verified.
​
created_at
datetime
Timestamp when the user account was created.

​
Example Request

curl -X GET https://api.example.com/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "[email protected]",
  "full_name": "John Doe",
  "is_active": true,
  "is_verified": false,
  "created_at": "2026-03-03T10:30:00Z"
}

​
Error Responses

​
401 Unauthorized

Returned when the access token is missing, invalid, or expired. 
{
  "detail": "Could not validate credentials"
}

​
403 Forbidden

Returned when the user account is inactive. 
{
  "detail": "Inactive user"
}

​
Authentication Flow

​
Using Access Tokens

Include the access token in the Authorization header for all authenticated requests: 
Authorization: Bearer <access_token>

​
Handling Token Expiration

  1. Make authenticated API request with access token
  2. If you receive a 401 error, the access token may be expired
  3. Call /api/auth/refresh with your refresh token
  4. Receive new access and refresh tokens
  5. Retry the original request with the new access token
  6. Store the new refresh token for future use

​
JWT Token Details

Access Token Payload: 
{
  "sub": "user-uuid",
  "email": "[email protected]",
  "type": "access",
  "exp": 1709467800,
  "iat": 1709466000
}
Token Properties:
  • Algorithm: HS256 (HMAC with SHA-256)
  • Access Token Expiration: 30 minutes (1800 seconds)
  • Refresh Token Expiration: 7 days
  • Refresh Token Storage: SHA-256 hashed

​
Logout

Invalidate the current refresh token, effectively logging out the user. The access token will continue to work until it expires (30 minutes), but cannot be refreshed.

​
Authentication

Requires valid JWT access token in Authorization header.

​
Request Body

​
refresh_token
string
required
The refresh token to invalidate.

​
Response

​
message
string
Confirmation message.
​
success
boolean
Always true on successful logout.

​
Example Request

cURL
curl -X POST http://localhost:8000/api/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

​
Example Response

{
  "message": "Successfully logged out",
  "success": true
}
After logout, the refresh token is permanently invalidated. The user must login again to obtain new tokens.

​
Error Responses

StatusDescription
400Bad Request - Missing refresh token
401Unauthorized - Invalid or expired access token
404Not Found - Refresh token not found or already revoked
500Internal Server Error

​
Token Details

​
JWT Token Format

Access tokens are JWT tokens with the following structure: Header: 
{
  "alg": "HS256",
  "typ": "JWT"
}
Payload: 
{
  "sub": "[email protected]",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "access",
  "exp": 1704454800,
  "iat": 1704453000
}

​
Token Lifetimes

  • Access Token Expiration: 30 minutes (1800 seconds)
  • Refresh Token Expiration: 7 days
  • Refresh Token Storage: SHA-256 hashed

​
Security Best Practices

  • Store tokens securely (never in localStorage for web apps)
  • Always use HTTPS in production
  • Implement token refresh before expiration
  • Handle token expiration gracefully
  • Call the logout endpoint when users log out
  • Clear tokens from storage after logout

Build docs developers (and LLMs) love

Get started for freeTalk to us