🔐 Authentication API

Secure authentication endpoints for user registration, login, and API key management.

Overview

The UConnect Gateway uses API keys for authentication. After registration or login, you'll receive an API key that must be included in all subsequent requests.

Authentication Methods

Include your API key in requests using one of these methods:

  • Header: X-API-Key: your_api_key
  • Bearer Token: Authorization: Bearer your_api_key
  • Query Parameter: ?api_key=your_api_key

Register New Account

POST /api/auth/register

Create a new user account and receive an API key.

Request Body

Field Type Required Description
username string ✅ Yes Unique username (alphanumeric)
email string ✅ Yes Valid email address
password string ✅ Yes Minimum 6 characters
phone string ❌ No Phone number with country code

Example Request

curl -X POST https://uconect.ulibtech.org/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "john@example.com",
    "password": "securepass123",
    "phone": "+256700000000"
  }'
const response = await fetch('https://uconect.ulibtech.org/api/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'john_doe',
    email: 'john@example.com',
    password: 'securepass123',
    phone: '+256700000000'
  })
});

const data = await response.json();
console.log(data);
import requests

url = 'https://uconect.ulibtech.org/api/auth/register'
data = {
    'username': 'john_doe',
    'email': 'john@example.com',
    'password': 'securepass123',
    'phone': '+256700000000'
}

response = requests.post(url, json=data)
print(response.json())

Response

{
  "success": true,
  "message": "Registration successful",
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "phone": "+256700000000",
    "credits": 5.00,
    "is_active": true,
    "is_admin": false,
    "created_at": "2024-12-25T10:30:00Z"
  },
  "api_key": "key_abc123def456...",
  "note": "Store your API key securely. You will need it for all authenticated requests."
}

Login

POST /api/auth/login

Authenticate and retrieve your API key.

Request Body

Field Type Required Description
username string ✅ Yes Username or email
password string ✅ Yes Account password

Example Request

curl -X POST https://uconect.ulibtech.org/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "securepass123"
  }'

Response

{
  "success": true,
  "api_key": "key_abc123def456...",
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "credits": 45.50,
    "is_admin": false
  }
}

Logout

POST /api/auth/logout

Invalidate your current API key.

Headers

Header Value
X-API-Key Your API key

Example Request

curl -X POST https://uconect.ulibtech.org/api/auth/logout \
  -H "X-API-Key: your_api_key_here"

Response

{
  "success": true,
  "message": "Logged out successfully"
}

Update Profile

PUT /api/user/profile

Update user profile information.

Request Body

Field Type Required Description
email string ❌ No New email address
phone string ❌ No New phone number
password string ❌ No New password (min 6 chars)

Example Request

curl -X PUT https://uconect.ulibtech.org/api/user/profile \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "email": "newemail@example.com",
    "phone": "+256700111222"
  }'

Response

{
  "success": true,
  "message": "Profile updated successfully"
}

Regenerate API Key

POST /api/user/regenerate-key

Generate a new API key. The old key will be invalidated immediately.

⚠️ Warning: This action will immediately invalidate your current API key. Update all your applications with the new key before regenerating.

Example Request

curl -X POST https://uconect.ulibtech.org/api/user/regenerate-key \
  -H "X-API-Key: your_current_api_key"

Response

{
  "success": true,
  "api_key": "key_new789xyz456...",
  "message": "API key regenerated successfully. Update your applications with the new key.",
  "warning": "Your old API key is now invalid."
}

Common Error Responses

Invalid Credentials

{
  "error": "Invalid credentials or inactive account"
}

Username Already Exists

{
  "error": "Username or email already exists"
}

Validation Error

{
  "error": "username, email and password are required"
}

Unauthorized

{
  "error": "API key required"
}

Account Inactive

{
  "error": "Account is inactive. Contact administrator."
}

Best Practices

🔒 Secure Storage

Store your API key securely. Never commit it to version control or expose it in client-side code.

🔄 Key Rotation

Regularly rotate your API keys, especially if you suspect unauthorized access.

🛡️ HTTPS Only

Always use HTTPS when making API requests to protect your API key in transit.

⚡ Error Handling

Implement proper error handling for authentication failures and expired sessions.