Authentication

Authentication answers a single question for every protected call: which merchant account is acting? The Order API uses short-lived JWTs for that answer.

Endpoints

The idea

You prove possession of an account’s email and password (or you create the account once via register). The API replies with an access token. On later calls you present that token; the API verifies it, loads the user, and only then runs the business logic. If the token is missing, forged, expired, or belongs to a user that no longer exists or is inactive, the call is rejected.

A small set of entry points — signing in, registering, and health — do not require a token. Everything that reads or changes orders does.

Why JWT Bearer

A JWT lets the API trust a signed statement (“this is user X until time T”) without asking for the password on every request. Bearer means the token is the credential: anyone who holds it can act as that user until it expires. That is why tokens must be stored carefully, sent only over HTTPS, and never placed in URLs or logs.

Send the token as:

Authorization: Bearer <accessToken>

What registration establishes

POST /api/v1/auth/register creates the merchant user and attaches Monta credentials to that user. From then on, Monta work for this account uses those stored credentials. The API never returns the Monta API key after signup or login — only a public profile (identity fields and Monta username). Passwords are stored hashed, not in plain text.

If email or Monta username is already taken, registration fails with a conflict. That protects account uniqueness and keeps Monta credential ownership unambiguous.

POST /api/v1/auth/login is the path for an existing account: email and password in, access token out.

What the token represents

The token carries the user’s id and email, plus standard issued-at and expiry claims. Default lifetime is about twenty-four hours. There is no refresh token; when expiry hits, call login again and receive a new access token.

On each protected request the API checks the signature and expiry, then reloads the user. Inactive users are treated as unauthorized even if a previously issued token has not yet expired by the clock.

How clients should behave

Send the token in the standard Authorization Bearer header on every order call. Rotate or replace it when login succeeds again. Assume that losing a token is equivalent to temporary account access for its remaining lifetime — keep it out of client-side public storage when possible, and prefer server-side or secure mobile storage patterns appropriate to your app.

Failure modes in plain language

Bad input on login or register (invalid email, short password, missing names or Monta fields) fails validation. Wrong password or unknown email fails as unauthorized. Reusing a taken email or Monta username on register fails as conflict. Calling order APIs without a usable token fails as unauthorized.

Authentication is intentionally simple today: one user, one token type, full access to that user’s order world for the token’s lifetime. Finer-grained permission strings are not part of the current model; ownership of the data is the boundary.