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

  • warnings (list-of-string) – Optional. List of warnings

  • individual_accounts (list-of-object) –

    Individual accounts

    Inner fields:

    • warnings (list-of-string) – List of warnings

    • 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:

    • warnings (list-of-string) – List of warnings

    • 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) – [min-length: 10] Password. Must contain at least one lowercase character, one uppercase character, one digit character and one non-alphanumeric character.

  • 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

  • warnings (list-of-string) – Optional. List of warnings

  • 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

  • ForbiddenError with error name INCORRECT_ACCOUNT if the account can’t be deleted because it has the ROOT role

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. [min-length: 10] Password. Must contain at least one lowercase character, one uppercase character, one digit character and one non-alphanumeric character.

  • 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) – [min-length: 12] Password. Must contain at least one lowercase character, one uppercase character, and one digit character.

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

  • name (string) – Service name

EXAMPLE QUERY BODY
  {
      "name": "myapp-server",
      "password": "myApp-P@ssw0rd",
      "role": "backend"
  }
Response JSON Object

  • warnings (list-of-string) – Optional. List of warnings

  • 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

  • ForbiddenError with error name INCORRECT_ACCOUNT if the account can’t be deleted because it has the ROOT role

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) – [min-length: 12] Password. Must contain at least one lowercase character, one uppercase character, and one digit character.

EXAMPLE QUERY BODY
  {
      "name": "myapp-server",
      "password": "newAppP@ssw0rd"
  }

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.

When both frontend_user_id and frontend_session_id are set, the anonymous session will be automatically resolved to the given user, so calling POST sessions/<str:session_id>/resolve/ is not necessary.

Main documentation page: Authentication.

Request JSON Object

  • password (string) – Password

  • db_id (string) – Optional. Database ID

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

  • frontend_session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Frontend anonymous session 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

  • warnings (list-of-string) – Optional. List of warnings

  • org_id (string) – Organization ID

  • token (string) – JWT token

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

  • refresh_token (string) – Refresh token

  • database (object) –

    Optional.

    Inner fields:

    • warnings (list-of-string) – List of warnings

    • 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

    • session_id_type (string) – [see Flexible Identifiers] Anonymous Session ID type

EXAMPLE RESPONSE
  {
      "token": "eyJ0eX...",
      "org_id": "WEdZJsRxKvBrn2B_m6ZA",
      "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",
        "session_id_type": "uuid",
        "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.

When both frontend_user_id and frontend_session_id are set, the anonymous session will be automatically resolved to the given user, so calling POST sessions/<str:session_id>/resolve/ is not necessary.

Main documentation page: Authentication.

Request JSON Object

  • password (string) – Password

  • db_id (string) – Optional. Database ID

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

  • frontend_session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Frontend anonymous session ID, for accounts with frontend role

  • name (string) – Service name

EXAMPLE QUERY BODY
  {
      "name": "myapp-web",
      "password": "myApp-P@ssw0rd",
      "db_id": "wSSZQbPxKvBrk_n2B_m6ZA",
      "frontend_user_id": 12358
  }
Response JSON Object

  • warnings (list-of-string) – Optional. List of warnings

  • org_id (string) – Organization ID

  • token (string) – JWT token

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

  • refresh_token (string) – Refresh token

  • database (object) –

    Optional.

    Inner fields:

    • warnings (list-of-string) – List of warnings

    • 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

    • session_id_type (string) – [see Flexible Identifiers] Anonymous Session ID type

EXAMPLE RESPONSE
  {
      "token": "eyJ0eX...",
      "org_id": "WEdZJsRxKvBrn2B_m6ZA",
      "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",
        "session_id_type": "uuid",
        "status": "ready"
      }
  }

Errors:

  • AuthError with error name INCORRECT_PASSWORD if the password is incorrect

Login as Root

POST login/root/

Warning

DEPRECATED

See POST login/individual/

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. Also it allows to change the database by using the db_id optional parameter. 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

  • db_id (string) – Optional. Database ID

EXAMPLE NON DB_ID
  {
      "refresh_token": "mW+k/K..."
  }
EXAMPLE QUERY BODY
  {
      "refresh_token": "mW+k/K...",
      "db_id": "wSSZQbPxKvBrk_n2B_m6ZA"
  }
Response JSON Object

  • warnings (list-of-string) – Optional. List of warnings

  • org_id (string) – Organization ID

  • token (string) – JWT token

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

  • refresh_token (string) – Refresh token

  • database (object) –

    Optional.

    Inner fields:

    • warnings (list-of-string) – List of warnings

    • 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

    • session_id_type (string) – [see Flexible Identifiers] Anonymous Session ID type

EXAMPLE RESPONSE
  {
      "token": "eyJ0eX...",
      "org_id": "WEdZJsRxKvBrn2B_m6ZA",
      "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",
        "session_id_type": "uuid",
        "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

  • warnings (list-of-string) – Optional. List of warnings

  • 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

  • warnings (list-of-string) – Optional. List of warnings

  • 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.