Authentication API
JWT-based authentication system for secure access to SysManage APIs with token refresh and session management.
Overview
SysManage uses JSON Web Tokens (JWT) for authentication. All API endpoints (except authentication endpoints) require a valid JWT token in the Authorization header.
Authentication Flow
- Send username and password to
/api/v1/auth/login - Receive access token and refresh token
- Include access token in Authorization header for API requests
- Use refresh token to get new access token when expired
Login
/api/v1/auth/login
Authenticate user credentials and receive JWT tokens for API access.
Request Body
{
"username": "string",
"password": "string"
}Response (200 OK)
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "bearer",
"expires_in": 3600,
"user": {
"id": "uuid",
"username": "string",
"email": "string",
"is_admin": false,
"created_at": "2024-01-01T00:00:00Z",
"last_login": "2024-01-01T00:00:00Z"
}
}Error Responses
{
"detail": "Invalid credentials"
}{
"detail": "Too many login attempts. Please try again later."
}Example
curl -X POST "https://your-server.example.com/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "secure-password"
}'Refresh Token
/api/v1/auth/refresh
Exchange a valid refresh token for a new access token when the current one expires.
Request Body
{
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}Response (200 OK)
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "bearer",
"expires_in": 3600
}Error Responses
{
"detail": "Invalid refresh token"
}Example
curl -X POST "https://your-server.example.com/api/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "your-refresh-token"
}'Password Reset
/api/v1/auth/forgot-password
Request a password reset email for user account recovery.
Request Body
{
"email": "user@example.com"
}Response (200 OK)
{
"message": "Password reset email sent successfully"
}Example
curl -X POST "https://your-server.example.com/api/v1/auth/forgot-password" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com"
}'Reset Password
/api/v1/auth/reset-password
Reset user password using a valid reset token received via email.
Request Body
{
"token": "reset-token-from-email",
"new_password": "new-secure-password"
}Response (200 OK)
{
"message": "Password reset successfully"
}Error Responses
{
"detail": "Invalid or expired reset token"
}Example
curl -X POST "https://your-server.example.com/api/v1/auth/reset-password" \
-H "Content-Type: application/json" \
-d '{
"token": "reset-token-from-email",
"new_password": "new-secure-password"
}'Validate Reset Token
/api/v1/auth/validate-reset-token/{token}
Validate if a password reset token is still valid and not expired.
Path Parameters
token(string) - The reset token to validate
Response (200 OK)
{
"valid": true,
"expires_at": "2024-01-01T01:00:00Z"
}Error Responses
{
"valid": false,
"detail": "Token expired or invalid"
}Example
curl -X GET "https://your-server.example.com/api/v1/auth/validate-reset-token/abc123"Using Authentication Tokens
Once you receive an access token from the login endpoint, include it in the Authorization header of all API requests:
Authorization: Bearer YOUR_ACCESS_TOKENToken Expiration
Access tokens expire after 1 hour (3600 seconds). When an access token expires, use the refresh token to obtain a new one without requiring the user to log in again.
Security Best Practices
- Store tokens securely and never expose them in client-side code
- Implement automatic token refresh before expiration
- Use HTTPS for all authentication requests
- Implement proper logout functionality to invalidate tokens
- Monitor for unusual authentication patterns