Authentication

Authentication resources for monetr's REST API.

Authentication is primarily broken up into three objects. Logins, users, and accounts. Each of these objects are different from each other, but all of them are related. Logins are used to represent a single person's credentials for accessing monetr, as well as some of their basic information like their name. Users are a child object of logins, and a single login can have multiple users. Users are tied to a single account. Accounts are how all data is separated inside the application. When you create a Plaid Link or expenses, or other budgeting items. They are created at an account level. Your login tells us what users represent you, and those users tell us what accounts you have access to.

Login

Provide login credentials to authenticate a user. This API will not respond with a token in the body. It stores the token in an HTTP only cookie to prevent it from being accessible from Javascript code in the browser. If the credentials are valid then you will receive a 200 OK status code in the response.

POST /api/authentication/login

Request Body

Response Body

??? note

When the request is successful the response body is pretty minimal. User details should be retrieved using a follow up request to Get Me

Login Examples

curl --request POST \
  --url "https://my.monetr.app/api/authentication/login" \
  --header "content-type: application/json" \
  --data '{
    "email": "email@example.com",
    "password": "superSecureP@ssw0rd"
}'

Successful

If the credentials provided are valid and there is nothing else to be done, then the response will simply be this.

{
  "isActive": true
}

Subscription is not active

If the subscription for the authenticated user is not active (or if there is no subscription at all), then the response body will contain a path indicating to the UI what the next URL should be.

{
  "isActive": false,
  "nextUrl": "/account/subscribe"
}

Login Errors

Invalid Credentials

If the credentials provided are not valid you will receive the following response body:

{
  "error": "invalid email and password"
}

Email is not verified

If email verification is required by the server, then it is possible to get a login failure response even with valid credentials. If the credentials provided are valid, but the login's email is not verified yet; then you will receive the following response.

{
  "error": "email address is not verified",
  "code": "EMAIL_NOT_VERIFIED"
}

MFA is required

That is not the only error that can result in a 428 status code, if the user requires MFA you will receive the same status code upon providing valid credentials. But the code in the error body will be different and represent what action needs to be taken by the user.

{
  "error": "login requires MFA",
  "code": "MFA_REQUIRED"
}

Logout

Because cookies are HTTP only, there is no way to remove the cookies from our UI code. Instead, we have a logout endpoint that removes the cookies.

GET /api/authentication/logout

Logout Examples

curl --request GET \
  --url "https://my.monetr.app/api/authentication/logout"

Logout does not return an error if the cookie is not present, it will always return a 200 status code with an empty response body.

Register

New users can register for monetr using this endpoint. It can be configured to require ReCAPTCHA to reduce the likelihood that the endpoint will be spammed. Even in self-hosted deployments, it will require a valid email address is used. ¹ Registering will create a new login, user, and account using the provided details.

If billing is enabled on the server, your email address will be used to create a Stripe customer. Stripe is used to manage subscriptions and this way Stripe has a way to contact you or vice versa if needed.

POST /api/authentication/register

Request Body

Response Body

Register Examples

curl --request POST \
  --url "https://my.monetr.app/api/authentication/register" \
  --header "content-type: application/json" \
  --data '{
    "email": "email@example.com",
    "password": "superSecureP@ssw0rd",
    "firstName": "Elliot",
    "lastName": "Courant",
    "timezone": "America/Chicago",
    "agree": true
}'

Successful

If the registration was successful and email verification is not necessary then you'll see a response body similar to the following.

{
  "nextUrl": "/setup",
  "user": {
    "loginId": 1234,
    "accountId": 1235,
    "userId": 1236,
    "login": {
      "loginId": 1234,
      "firstName": "Elliot",
      "lastName": "Courant",
    },
    "account": {
      "accountId": 1235,
      "timezone": "America/Chicago"
    }
  },
  "isActive": true,
  "requireVerification": false
}

Email verification required

If the registration succeeds, but we need to verify the login's email address.

{
  "message": "A verification email has been sent to your email address, please verify your email.",
  "requireVerification": true
}

Email already exists

If the provided email is already in use by someone else for monetr then you will receive a bad request response.

{
  "error": "email already in use",
  "code": "EMAIL_IN_USE"
}