Authentication

The API uses JWT (JSON Web Tokens) for authentication. Tokens are obtained via the login endpoint and passed in the Authorization header for all protected requests.

Login

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

Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2026-02-24T10:30:00Z",
    "username": "admin",
    "role": "admin"
  }
}

Using the Token

Include the token in the Authorization header with the Bearer prefix:

curl http://localhost:8081/api/v1/invoices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Format

JWT payload claims:

{
  "sub": "admin",
  "role": "admin",
  "exp": 1740394200,
  "iat": 1740307800
}

Claim	Description
sub	Username
role	User role (admin, manager, viewer)
exp	Expiration timestamp (Unix)
iat	Issued at timestamp (Unix)

Token Expiration

Tokens expire after the configured duration (default: 24 hours). When a token expires, the API returns:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "token expired"
  }
}

The client should re-authenticate via the login endpoint.

Configuration

INVOICE_JWT_SECRET=your-secret-key  # Required, used to sign tokens

Unauthenticated Endpoints

The following endpoints do not require authentication:

• GET /healthz — Liveness probe
• GET /readyz — Readiness probe
• POST /api/v1/auth/login — Authentication