Skip to main content

Authentication

BillManager API v2 uses JWT (JSON Web Tokens) for authentication.

Overview​

The API uses a two-token system:

  • Access Token - Short-lived (15 minutes), used for API requests
  • Refresh Token - Long-lived (7 days), used to get new access tokens

Getting Tokens​

Login​

POST /api/v2/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": 1,
      "email": "[email protected]",
      "is_admin": false
    },
    "databases": [
      {"id": 1, "name": "My Bills"}
    ]
  }
}

Using the Access Token​

Include the access token in the Authorization header:

GET /api/v2/bills
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
X-Database: My Bills

Refreshing Tokens​

When the access token expires, use the refresh token:

POST /api/v2/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Response:

{
  "success": true,
  "data": {
    "access_token": "new-access-token..."
  }
}

Logout​

Single Device​

POST /api/v2/auth/logout
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "refresh_token": "your-refresh-token"
}

All Devices​

POST /api/v2/auth/logout-all
Authorization: Bearer <access_token>

Database Selection​

Most endpoints require specifying which Bill Group to access:

X-Database: My Bills

Or use the database ID:

X-Database-Id: 1

Error Responses​

Invalid Credentials​

{
  "success": false,
  "error": "Invalid email or password"
}

Token Expired​

{
  "success": false,
  "error": "Token has expired"
}

Missing Token​

{
  "success": false,
  "error": "Missing Authorization header"
}

Best Practices​

  1. Store tokens securely - Never expose in URLs or logs
  2. Refresh proactively - Refresh before expiration
  3. Handle expiration - Catch 401 errors and refresh
  4. Logout on sign out - Revoke refresh tokens