Authentication API Reference

Manage user authentication, token generation, and password reset operations.

Base Path: /api/auth

Overview

The Authentication API handles all user authentication operations including login, logout, token generation, and password recovery. All authentication endpoints return JWT tokens for subsequent API requests.

Authentication Methods

API Endpoints

GET /api/auth

Get User Access Token

Gets user access token from Basic Authentication credentials.

Authentication

Uses HTTP Basic Authentication (username:password)

Request

Header Value Required
Authorization Basic base64(username:password) Yes
Content-Type application/json No

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}
POST /api/auth/logout

Logout

Logs out user by invalidating refresh token.

Authentication

Bearer Token

Request Body

{
  "refreshToken": "refresh_token_here"
}

Response

{
  "success": true,
  "message": "Logged out successfully"
}
POST /api/auth/forgot-password

Forgot Password

Initiates password reset and sends email with reset link.

Authentication

None

Request Body

{
  "email": "user@example.com"
}

Response

{
  "success": true,
  "message": "Password reset link sent to email"
}
POST /api/auth/reset-password

Reset Password

Resets user password using reset token received via email.

Authentication

None

Request Body

{
  "resetToken": "token_from_email",
  "newPassword": "new_secure_password"
}

Response

{
  "success": true,
  "message": "Password reset successfully"
}
GET /api/auth/user

Get User Token (Admin)

Gets access token for specified user (Admin only).

Authentication

Bearer Token (Admin role required)

Query Parameters

Parameter Type Description
userId integer User ID
username string Username

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "userId": 123,
  "username": "john_doe",
  "expiresIn": 3600
}
GET /api/auth/account

Get Account Access Token

Gets access token scoped to specific account.

Authentication

Bearer Token

Query Parameters

Parameter Type Description
accountId integer Account ID (optional)

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "accountId": 456,
  "accountName": "Acme Corp",
  "expiresIn": 3600
}
POST /api/auth/access-token

Get Access Token from Refresh Token

Obtains new access token using refresh token.

Authentication

None

Request Body

{
  "refreshToken": "refresh_token_here"
}

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600
}
GET /api/auth/transient

Get Access Token from Transient Code

Gets access token from password reset code.

Authentication

None

Query Parameters

Parameter Type Description
code string Transient token code from email

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 1800
}

Error Responses

{
  "code": "INVALID_CREDENTIALS",
  "message": "Invalid username or password",
  "timestamp": "2026-06-02T10:30:00Z"
}

Common Error Codes

Code HTTP Status Description
INVALID_CREDENTIALS 401 Invalid username or password
USER_NOT_FOUND 404 User does not exist
TOKEN_EXPIRED 401 Token has expired
INVALID_TOKEN 401 Token is invalid or malformed
WEAK_PASSWORD 400 Password does not meet requirements

Quick Links

← Back to Overview Accounts API → Try the Playground