Authentication

Users must be authenticated before they can interact with most of the Bloom API endpoints (any endpoints requiring permissions). Authentication is done via a Bearer token (described below), or with an API key.

For more information, see headers.

Login

Login to your account to obtain an access token and refresh token. The access token is used to authenticate requests to the API, while the refresh token is used to obtain a new access token when the current one expires.

POST /auth/login

Example body

{
  "email": "user@example.com",
  "password": "password"
}

Fields

• email
  required string
  Email address of the user.
• password
  required string
  Password of the user.

Response

The Bloom API enforces a 2FA (two-factor authentication) policy for all users authenticating using the login endpoint. Upon successful login, the API will return a 201 No Content response and an email will be sent to the user with a one-time authentication code which is valid for 15 minutes. This code must be submitted to the /auth/tfa endpoint to complete the login process and obtain access and refresh tokens.

Successful login attempts can only be completed once per 3-minute period. If a user attempts to log in again within 3 minutes of a successful login, they will receive a 429 Too Many Requests response and will not be sent a new one-time authentication code. After 3 minutes, the user can attempt to log in again and will receive a new one-time authentication code.

TFA

The TFA (two-factor authentication) endpoint is used to complete the login process after a successful login attempt.

POST /auth/tfa

Example body

{
  "email": "user@example.com",
  "token": "TOKEN"
}

Fields

• email
  required string
  Email address of the user.
• token
  required string
  One-time authentication code sent to the user's email address.

Response

Authentication object

{
  "data": {
    "user": "019eb9a9-ea8e-71d1-944e-7r7d2di9f122",
    "access": "ACCESS_TOKEN",
    "refresh": "REFRESH_TOKEN",
    "expires": 1783176140
  }
}

Fields

• user
  required readonly string
  Unique ID of the user.
• access
  required readonly string
  Access token to be used in the Authorization header for subsequent requests.
• refresh
  required readonly string
  Refresh token to be used to obtain a new access token.
• expires
  required readonly integer
  UTC timestamp of when the access token expires.

Access tokens are valid for 15 minutes. Refresh tokens are valid for 7 days. The refresh token can be submitted to the auth/refresh endpoint to obtain new access and refresh tokens without having to log in again.

Refresh

The refresh endpoint is used to obtain new access and refresh tokens using a valid refresh token.

POST /auth/refresh

Example body

{
  "refresh_token": "REFRESH_TOKEN"
}

Fields

• refresh_token
  required string
  Refresh token obtained from the authentication object.

Response