Authentication

The API uses JWT bearer tokens for authentication. You'll get two tokens when you log in — each with a different purpose and lifetime.

Token types

Token	Lifetime	Purpose
Access token	Short-lived	Passed as Authorization: Bearer <token> on every request
Refresh token	Long-lived	Used to obtain a new access token when the current one expires

Recommended flow

┌─────────┐          ┌───────────┐
│  Login  │────────→ │ Get both  │
│         │          │  tokens   │
└─────────┘          └─────┬─────┘
                           │
                     ┌─────▼─────┐
              ┌──────│  Use API  │◄────────┐
              │      │  normally │         │
              │      └─────┬─────┘         │
              │            │               │
              │      ┌─────▼─────┐   ┌─────┴─────┐
              │      │    401?   │──→│  Refresh  │
              │      └───────────┘   │   token   │
              │                      └───────────┘
              │
        ┌─────▼──────┐
        │  Refresh   │
        │  also 401? │──→  Re-login
        └────────────┘

Step by step

1. Login — Call POST /v1/auth/login with your email and password. Store both the accessToken and refreshToken.

2. Use the access token — Include it in every API request:

   Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

3. Handle expiration — When you receive a 401 Unauthorized response, your access token has expired. Call POST /v1/auth/refresh with your refresh token to get a new access token.

4. Re-login if needed — If the refresh token itself is expired or revoked, you'll get a 401 from the refresh endpoint too. In that case, log in again with POST /v1/auth/login.

Security best practices

• Store tokens securely — never expose tokens in client-side code, URLs, or logs
• Refresh proactively — instead of waiting for a 401, you can decode the JWT to check its expiration time and refresh before it expires
• Revoke on logout — call POST /v1/auth/revoke when a user session ends to invalidate the refresh token
• Revoke all in emergencies — if you suspect a token has been compromised, call POST /v1/auth/revoke-all to invalidate all sessions

FAQ

How long do tokens last?

Access tokens are short-lived (60 minutes). Refresh tokens are long-lived (30 days). You can decode the JWT to check the exact expiration time in the exp claim.

Can I use the same token across multiple services?

Yes. The access token is a standard JWT and can be used in parallel from multiple services or instances. However, each service should handle token refresh independently to avoid race conditions.

What happens if my refresh token is revoked?

Any attempt to refresh will return a 401. You will need to log in again with POST /v1/auth/login to get a new pair of tokens.

Do I need to revoke tokens when rotating credentials?

Yes. Changing your password does not automatically invalidate existing tokens. Call POST /v1/auth/revoke-all to invalidate all active sessions after a password change.