Authentication Flow

List All Accounts

GET organizations/current/accounts/

Note

Authorized Roles: root, manager

This endpoint allows you to get all the accounts that belong to the organization of the token.

Response JSON Object
  • individual_accounts (list-of-object) –

    Individual accounts

    Inner fields:

    • role (enum) – choices: [root, manager, backend, frontend, demo_viewer] Role

    • first_name (string) – First name

    • last_name (string) – Last name

    • email (email) – Email address

    • verified (bool) – Account verified

  • service_accounts (list-of-object) –

    Service accounts

    Inner fields:

    • role (enum) – choices: [root, manager, backend, frontend, demo_viewer] Role

    • name (string) – Service name

EXAMPLE RESPONSE
  {
      "individual_accounts": [
          {
              "first_name": "John",
              "last_name": "Doe",
              "email": "john@example.com",
              "role": "manager",
              "verified": true
          }
      ],
      "service_accounts": [
          {
              "name": "myapp-server",
              "role": "backend"
          }
      ]
  }

Create Individual Account

POST accounts/individual/

Note

Authorized Roles: root, manager

This endpoint allows you to create a new account for an individual, identified by an email. To create a new account it is necessary to have generated a token previously (using login, for instance with the root account).

Main documentation page: Authentication.

Request JSON Object
  • password (string) – Password

  • role (enum) – choices: [manager, backend, frontend, demo_viewer] Role

  • first_name (string) – First name

  • last_name (string) – Last name

  • email (email) – Email address

EXAMPLE QUERY BODY
  {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "password": "MyP@ssw0rd",
      "role": "manager"
  }
Response JSON Object
  • id (string) – Account ID

EXAMPLE RESPONSE
  {
      "id": "z3hn6UoSYWtK4KUA"
  }

Errors:

  • DuplicatedError with error name DUPLICATED_ACCOUNT if an individual account with the same email already exists

Delete Individual Account

DELETE accounts/individual/

Note

Authorized Roles: root, manager

This endpoint allows you to delete another individual account by email address that belong to the organization of the token.

Request JSON Object
  • email (email) – Email address

EXAMPLE QUERY BODY
  {
      "email": "john@example.com",
  }

Errors:

  • NotFoundError with error name ACCOUNT_NOT_FOUND if the account does not exist

Partial Update Individual Account

PATCH accounts/individual/

Note

Authorized Roles: root, manager

This endpoint allows you to update the password or other editable property of an individual account, identified by an email. Editable properties not provided will not be modified.

Request JSON Object
  • email (email) – Email address

  • password (string) – Optional. Password

  • first_name (string) – Optional. First name

  • last_name (string) – Optional. Last name

EXAMPLE QUERY BODY
  {
      "email": "john@example.com",
      "password": "MyN3wP@ssw0rd"
  }

Errors:

  • NotFoundError with error name ACCOUNT_NOT_FOUND if the account does not exist

Create Service Account

POST accounts/service/

Note

Authorized Roles: root, manager

This endpoint allows you to create a new service account, identified by a service name. To create a new account it is necessary to have generated a token previously (using login, for instance with the root account).

Main documentation page: Authentication.

Request JSON Object
  • password (string) – Password

  • role (enum) – choices: [manager, backend, frontend, demo_viewer] Role

  • name (string) – Service name

EXAMPLE QUERY BODY
  {
      "name": "myapp-server",
      "password": "abc123@#$",
      "role": "backend"
  }
Response JSON Object
  • id (string) – Account ID

EXAMPLE RESPONSE
  {
      "id": "z3hn6UoSYWtK4KUA"
  }

Errors:

  • DuplicatedError with error name DUPLICATED_ACCOUNT if a service account with the same name already exists

Delete Service Account

DELETE accounts/service/

Note

Authorized Roles: root, manager

This endpoint allows you to delete another service account by name that belong to the organization of the token.

Request JSON Object
  • name (string) – Service name

EXAMPLE QUERY BODY
  {
      "name": "myapp-server",
  }

Errors:

  • NotFoundError with error name ACCOUNT_NOT_FOUND if the account does not exist

Partial Update Service Account

PATCH accounts/service/

Note

Authorized Roles: root, manager

This endpoint allows you to update the password or other editable property of an existing service account, identified by a service name. Editable properties not provided will not be modified.

Request JSON Object
  • name (string) – Service name

  • password (string) – Password

EXAMPLE QUERY BODY
  {
      "name": "myapp-server",
      "password": "Newabc123@#$"
  }

Errors:

  • NotFoundError with error name ACCOUNT_NOT_FOUND if the account does not exist

Login as Individual Account

POST login/individual/

This endpoint allows you to login on a database with your account, using your email and password combination. A JWT token and a refresh_token will be given in the body of the response. Please place the JWT token as Bearer value in the Authorization header to authenticate your following requests, and keep the refresh_token securely to get a new JWT token when it expires.

The JWT token expiration time is currently 1 hour, but we may reduce this value in the future without notice.

Main documentation page: Authentication.

Request JSON Object
  • password (string) – Password

  • db_id (string) – Database ID

  • frontend_user_id (ID) – Optional. [see Flexible Identifiers] Frontend user ID, for accounts with frontend role

  • email (email) – Email address

EXAMPLE QUERY BODY
  {
      "email": "john@example.com",
      "password": "MyP@ssw0rd",
      "db_id": "wSSZQbPxKvBrk_n2B_m6ZA"
  }
Response JSON Object
  • token (string) – JWT token

  • role (enum) – choices: [root, manager, backend, frontend, demo_viewer] Role

  • refresh_token (string) – Refresh token

  • database (object) –

    Inner fields:

    • status (string) – either “pending” or “ready”

    • id (string) – Database ID

    • name (string) – Database name

    • description (string) – Database long description

    • item_id_type (string) – [see Flexible Identifiers] Item ID type

    • user_id_type (string) – [see Flexible Identifiers] User ID type

EXAMPLE RESPONSE
  {
      "token": "eyJ0eX...",
      "role": "frontend",
      "refresh_token": "mW+k/K...",
      "database" : {
        "id": "wSSZQbPxKvBrk_n2B_m6ZA",
        "name": "Example DB name",
        "description": "Example DB longer description",
        "item_id_type": "uuid",
        "user_id_type": "uint32",
        "status": "ready"
      }
  }

Errors:

  • AuthError with error name INCORRECT_PASSWORD if the password is incorrect

  • AuthError with error name ACCOUNT_NOT_VERIFIED if the email has not been verified

Login as Service Account

POST login/service/

This endpoint allows you to login on a database with a service account, using a service name and password combination. A JWT token and a refresh_token will be given in the body of the response. Please place the JWT token as Bearer value in the Authorization header to authenticate your following requests, and keep the refresh_token securely to get a new JWT token when it expires.

The JWT token expiration time is currently 1 hour, but we may reduce this value in the future without notice.

Main documentation page: Authentication.

Request JSON Object
  • password (string) – Password

  • db_id (string) – Database ID

  • frontend_user_id (ID) – Optional. [see Flexible Identifiers] Frontend user ID, for accounts with frontend role

  • name (string) – Service name

EXAMPLE QUERY BODY
  {
      "name": "myapp-web",
      "password": "abc123@#$",
      "db_id": "wSSZQbPxKvBrk_n2B_m6ZA",
      "frontend_user_id": 12358
  }
Response JSON Object
  • token (string) – JWT token

  • role (enum) – choices: [root, manager, backend, frontend, demo_viewer] Role

  • refresh_token (string) – Refresh token

  • database (object) –

    Inner fields:

    • status (string) – either “pending” or “ready”

    • id (string) – Database ID

    • name (string) – Database name

    • description (string) – Database long description

    • item_id_type (string) – [see Flexible Identifiers] Item ID type

    • user_id_type (string) – [see Flexible Identifiers] User ID type

EXAMPLE RESPONSE
  {
      "token": "eyJ0eX...",
      "role": "frontend",
      "refresh_token": "mW+k/K...",
      "database" : {
        "id": "wSSZQbPxKvBrk_n2B_m6ZA",
        "name": "Example DB name",
        "description": "Example DB longer description",
        "item_id_type": "uuid",
        "user_id_type": "uint32",
        "status": "ready"
      }
  }

Errors:

  • AuthError with error name INCORRECT_PASSWORD if the password is incorrect

Login as Root

POST login/root/

This endpoint allows you to login with the root account, without selecting any database. This is useful to create new databases, or create new accounts. A JWT token will be given in the body of the response. No refresh_token will be given, since using the root account without database is only for temporary steps. Please place the JWT token as Bearer value in the Authorization header to authenticate your following requests.

The JWT token expiration time is currently 1 hour, but we may reduce this value in the future without notice.

Main documentation page: Authentication.

Request JSON Object
  • email (email) – Email address

  • password (string) – Password

EXAMPLE QUERY BODY
  {
      "email": "john@example.com",
      "password": "MyP@ssw0rd"
  }
Response JSON Object
  • token (string) – JWT token

EXAMPLE RESPONSE
  {
      "token": "eyJ0eX..."
  }

Errors:

  • AuthError with error name INCORRECT_PASSWORD if the password is incorrect

Renew Login with Refresh Token

POST login/refresh-token/

This endpoint allows you to login on a database with your account, using a refresh token. A new JWT token and a (potentially new) refresh_token will be given in the body of the response. In your following requests, place the new JWT token as Bearer value in the Authorization header, and keep the potentially new refresh_token for future refreshing.

The refresh_token expiration time is currently 60 days, but we may reduce this value in the future without notice.

Main documentation page: Authentication.

Request JSON Object
  • refresh_token (string) – Refresh token

EXAMPLE QUERY BODY
  {
      "refresh_token": "mW+k/K..."
  }
Response JSON Object
  • token (string) – JWT token

  • role (enum) – choices: [root, manager, backend, frontend, demo_viewer] Role

  • refresh_token (string) – Refresh token

  • database (object) –

    Inner fields:

    • status (string) – either “pending” or “ready”

    • id (string) – Database ID

    • name (string) – Database name

    • description (string) – Database long description

    • item_id_type (string) – [see Flexible Identifiers] Item ID type

    • user_id_type (string) – [see Flexible Identifiers] User ID type

EXAMPLE RESPONSE
  {
      "token": "eyJ0eX...",
      "role": "frontend",
      "refresh_token": "mW+k/K...",
      "database" : {
        "id": "wSSZQbPxKvBrk_n2B_m6ZA",
        "name": "Example DB name",
        "description": "Example DB longer description",
        "item_id_type": "uuid",
        "user_id_type": "uint32",
        "status": "ready"
      }
  }

Errors:

  • NotFoundError with error name ACCOUNT_NOT_FOUND if the account has been deleted

  • AuthError with error name INCORRECT_REFRESH_TOKEN if the refresh token is invalid

  • RefreshTokenExpired with error name REFRESH_TOKEN_EXPIRED if the refresh token is expired

Resend Email Verification Code

PUT accounts/resend-verification-code/

This endpoint will send a new verification code to the email address of an individual account.

Main documentation page: Authentication.

Request JSON Object
  • email (email) – Email address

EXAMPLE QUERY BODY
  {
      "email": "john@example.com"
  }

Errors:

  • NotFoundError with error name ACCOUNT_NOT_FOUND if the email does not exist

  • AuthError with error name ACCOUNT_ALREADY_VERIFIED if the email has already been verified

Verify Email

POST accounts/verify/

This endpoint allows you to verify the email of an individual account. You can’t use an individual account without verifying the email. If you didn’t receive our email, please see PUT accounts/resend-verification-code/.

Main documentation page: Authentication.

Request JSON Object
  • code (string) – Verification code

  • email (email) – Email address

EXAMPLE QUERY BODY
  {
      "code": "abcd1234",
      "email": "john@example.com"
  }
Response JSON Object
  • email (email) – Email address

  • verified (bool) – Account verified

EXAMPLE RESPONSE
  {
      "verified": true,
      "email": "john@example.com"
  }

Errors:

  • NotFoundError with error name ACCOUNT_NOT_FOUND if the email does not exist

  • AuthError with error name ACTIVATION_CODE_DOES_NOT_MATCH if the code is incorrect

Verify Email Using GET

GET accounts/verify/

This endpoint allows you to verify the email of an individual account. You can’t use an individual account without verifying the email. If you didn’t receive our email, please see PUT accounts/resend-verification-code/.

Deprecated, you should use a POST method instead.

Main documentation page: Authentication.

Query Parameters
  • code (string) – Verification code

  • email (email) – Email address

EXAMPLE QUERY PARAMS
  ?code=abcd1234&email=john@example.com
Response JSON Object
  • email (email) – Email address

  • verified (bool) – Account verified

EXAMPLE RESPONSE
  {
      "verified": true,
      "email": "john@example.com"
  }

Errors:

  • NotFoundError with error name ACCOUNT_NOT_FOUND if the email does not exist

  • AuthError with error name ACTIVATION_CODE_DOES_NOT_MATCH if the code is incorrect

Delete Current Account

DELETE accounts/

This endpoint allows you to delete the account you’re logged to with your current token.