Authentication

Authentication API

The Authentication API provides endpoints for user login, logout, and token validation in your PoloCloud instance.

Login

Authenticate a user and receive an authentication token.

Endpoint: POST /polocloud/api/v3/auth/login

Request Body:

{
  "username": "admin",
  "password": "your-secure-password"
}

Response:

{
  "status": 200,
  "message": "Login successful"
}

Error Responses:

• 400 - Username is required / Password is required
• 401 - Invalid credentials

Logout

Logout the current user and invalidate their token.

Endpoint: POST /polocloud/api/v3/auth/logout

Response:

{
  "status": 200,
  "message": "Logout successful"
}

Check Token

Validate if the current authentication token is valid.

Endpoint: GET /polocloud/api/v3/auth/token

Response:

{
  "status": 200,
  "message": "Token is valid",
  "data": {
    "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
  }
}

Error Responses:

• 401 - No token found

Authentication Flow

1. Initial Setup

First, create an admin account using the Users API:

curl -X POST "http://localhost:8080/polocloud/api/v3/user/self" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-secure-password",
    "roleId": -1
  }'

2. Login

Authenticate with your credentials:

curl -X POST "http://localhost:8080/polocloud/api/v3/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-secure-password"
  }'

3. Use Token

Include the token in subsequent requests:

curl -X GET "http://localhost:8080/polocloud/api/v3/user/self" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

4. Logout

When done, logout to invalidate the token:

curl -X POST "http://localhost:8080/polocloud/api/v3/auth/logout" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Token Management

Token Storage

• HTTP-Only Cookies - Tokens are stored in secure HTTP-only cookies
• 7-Day Expiration - Tokens expire after 7 days
• Secure Flag - Cookies are marked as secure for HTTPS
• Automatic Cleanup - Tokens are automatically removed on logout

Token Validation

• Automatic Validation - All protected endpoints validate tokens automatically
• Permission Checking - Tokens include user permissions for authorization
• IP Tracking - Tokens are tied to the IP address that created them
• User Agent Tracking - Tokens track the user agent for security

Security Features

Password Security

• Encrypted Storage - Passwords are hashed using Argon2
• No Plain Text - Passwords are never stored in plain text
• Change Required - Users must change their password on first login

Token Security

• JWT Tokens - Uses JSON Web Tokens for authentication
• Secure Cookies - Tokens are stored in HTTP-only cookies
• Expiration - Tokens automatically expire after 7 days
• Revocation - Tokens can be manually revoked

Usage Examples

Login with cURL

curl -X POST "http://localhost:8080/polocloud/api/v3/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-secure-password"
  }'

Check Token Validity

curl -X GET "http://localhost:8080/polocloud/api/v3/auth/token" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Logout

curl -X POST "http://localhost:8080/polocloud/api/v3/auth/logout" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Using with Postman

1. Login - Send POST request to /auth/login with username/password
2. Save Token - Copy the token from the response
3. Set Cookie - Add token=YOUR_TOKEN to the cookies tab
4. Make Requests - Use the cookie for all authenticated requests
5. Logout - Send POST request to /auth/logout when done