Skip to main content

​
Overview

Borg UI uses JWT (JSON Web Token) based authentication with OAuth2 password flow. Most API endpoints require a valid access token.

​
Login

Authenticate and obtain an access token. Endpoint: POST /api/auth/login
​
username
string
required
Username for authentication
​
password
string
required
Password for authentication
Example Request: 
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=your_password"
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 43200,
  "must_change_password": false
}
​
access_token
string
JWT access token to use for authenticated requests
​
token_type
string
Always “bearer”
​
expires_in
integer
Token expiration time in seconds (default: 43200 = 12 hours)
​
must_change_password
boolean
If true, user must change their password before accessing other endpoints

​
Using the Token

Include the access token in the Authorization header: 
curl http://localhost:5000/api/repositories \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Current User

Retrieve information about the authenticated user. Endpoint: GET /api/auth/me Example Request: 
curl http://localhost:5000/api/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "id": 1,
  "username": "admin",
  "email": "[email protected]",
  "is_active": true,
  "is_admin": true,
  "must_change_password": false,
  "last_login": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T00:00:00Z"
}

​
Refresh Token

Obtain a new access token before the current one expires. Endpoint: POST /api/auth/refresh Example Request: 
curl -X POST http://localhost:5000/api/auth/refresh \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 43200
}

​
Logout

Invalidate the current session (client should discard the token). Endpoint: POST /api/auth/logout Example Request: 
curl -X POST http://localhost:5000/api/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
{
  "message": "Successfully logged out"
}

​
Change Password

Change the current user’s password. Endpoint: POST /api/auth/change-password
​
current_password
string
required
Current password
​
new_password
string
required
New password to set
Example Request: 
curl -X POST http://localhost:5000/api/auth/change-password \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "old_password",
    "new_password": "new_secure_password"
  }'
Response: 
{
  "message": "Password changed successfully"
}

​
Authentication Configuration

Get authentication configuration for the UI. Endpoint: GET /api/auth/config Example Request: 
curl http://localhost:5000/api/auth/config
Response: 
{
  "proxy_auth_enabled": false,
  "authentication_required": true
}

​
User Management (Admin Only)

​
List Users

Endpoint: GET /api/auth/users Example Request: 
curl http://localhost:5000/api/auth/users \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

​
Create User

Endpoint: POST /api/auth/users
​
username
string
required
Username for the new user
​
password
string
required
Password for the new user
​
email
string
Email address
​
is_admin
boolean
default:false
Whether user has admin privileges
Example Request: 
curl -X POST http://localhost:5000/api/auth/users \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "secure_password",
    "email": "[email protected]",
    "is_admin": false
  }'

​
Update User

Endpoint: PUT /api/auth/users/{user_id}

​
Delete User

Endpoint: DELETE /api/auth/users/{user_id} Example Request: 
curl -X DELETE http://localhost:5000/api/auth/users/2 \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us