Authentication

JWT-based authentication for the Borg UI API

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": "[e-mail]",
  "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": "[e-mail]",
    "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"