Authentication

Public endpoints under /auth/*. No token is needed to call them - this is how you get one.

Once you have a token, send it on every /api/* request:

Authorization: Bearer <token>

The token is either a login JWT (this page) or an API key for non-interactive use (see API keys).

Register

POST /auth/register

{
  "username": "alice",
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "alice@example.com",
  "password": "supersecret",
  "passwordConfirm": "supersecret"
}

password and passwordConfirm must match. Returns 201 with the newly created user. The first person to register creates the account and becomes its Owner:

{
  "id": "...",
  "username": "alice",
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "alice@example.com",
  "accountRole": "owner",
  "isActive": true,
  "isVerified": false,
  "createdAt": "..."
}

We send a verification email straight away. You can log in before verifying, but /api/* calls are blocked until your email is verified (see below). A username or email that's already taken returns 409.

Login

POST /auth/login

{
  "username": "alice",
  "password": "supersecret"
}

username is the username you registered with - your email address will not work here.

Response - just a token, nothing else:

{ "token": "eyJhbGciOiJIUzI1NiIs..." }

That token is a JWT carrying your account and user identity. Send it as Authorization: Bearer <token> on your API calls.

No refresh, no logout

The token expires on a timer (about an hour by default). There is no refresh endpoint and no logout endpoint - when it expires, just log in again. To "log out", discard the token on your side. Stateless and simple.

Too many wrong guesses

Eight failed logins for the same username within 15 minutes returns 429 Too many requests. A correct password clears the counter. Wait out the window, or reset your password.

Verify account

POST /auth/verify-account/:token

:token is the verification token from the signup email. Until you verify, /api/* calls return 403.

Resend verification email

POST /auth/resend-verification-email

{ "email": "alice@example.com" }

Request a password reset

POST /auth/reset-password-request

{ "email": "alice@example.com" }

Always returns 200, whether or not that email has an account - we are not going to tell a stranger which addresses are registered. If it exists, a reset link lands in the inbox.

Complete a password reset

POST /auth/reset-password

{
  "token": "...",
  "password": "newsecret",
  "passwordConfirm": "newsecret"
}

token comes from the reset email; password and passwordConfirm must match. Resetting your password signs out every existing session.

Programmatic access

Logging in with a username and password is for humans. For scripts, CI, or the automation / MCP endpoint, create an API key instead - it does not expire and you can scope it down to exactly what it needs.

Example

curl -X POST https://cloud-api.microapps.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"supersecret"}'