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:

  • id (string) – Account ID

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

  • first_name (string) – First name

  • last_name (string) – Last name

  • email (email) – Email address

  • metadata (object) – Metadata

• service_accounts (list-of-object) –

  Service accounts

  Inner fields:

  • name (string) – Service name

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

  • metadata (object) – Metadata

  • keys (list-of-object) – Keys

    Inner fields:

    • id (string) – Key ID

    • created_timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Created timestamp

    • expiration_timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Expiration timestamp

    • is_expired (bool) – True if the key expired

    • metadata (object) – Metadata

EXAMPLE RESPONSE

  {
      "individual_accounts": [
          {
              "first_name": "John",
              "last_name": "Doe",
              "email": "john@example.com",
              "role": "manager"
          }
      ],
      "service_accounts": [
          {
              "name": "myapp-server",
              "role": "backend",
              "keys": [
                  {
                      "id": "aeF32..",
                      "created_timestamp": 12341234.4,
                      "expiration_timestamp": 12345234.4,
                      "is_expired": false,
                      "metadata": {"description": "key for test"}
                  }
              ]
          }
      ]
  }

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

When the password parameter is not in the request, we will automatically send set password request by email.

Main documentation page: Authentication.

Request JSON Object

• email (email) – Email address

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

• first_name (string) – Optional. First name

• last_name (string) – Optional. Last name

• metadata (object) – Optional. Individual account Metadata

• email_redirect_url (string) – Optional. Email redirect URL. It will send set password email if it is not None and the password is None. The code and the code expiration will be added to the URL as query parameter, and then added to the body email.

• password (string) – Optional. [min-length: 10] [Deprecated] setting password on account creation is deprecated, but kept for backward compatibility until the new email flow UI is implemented. Must contain at least one lowercase character, one uppercase character, one digit character and one non-alphanumeric character.

EXAMPLE QUERY BODY

  {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "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

• metadata (object) – Optional. Individual account Metadata

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 multiple keys for the same service account must use the endpoint: POST accounts/service/keys/.

Main documentation page: Authentication.

Request JSON Object

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

• name (string) – Service name

• metadata (object) – Optional. Metadata

• password (string) – Optional. [min-length: 12] [Deprecated] use service key instead. If you set this value, it will actually create a key with this value. Must contain at least one lowercase character, one uppercase character, and one digit character.

EXAMPLE QUERY BODY

  {
      "name": "myapp-server",
      "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

Create Service Account Key

POST accounts/service/keys/

Note

Authorized Roles: root, manager

This endpoint allows you to create a service account key. It will randomly generate a key that will be returned in the response.

Request JSON Object

• name (string) – Service name

• expiration_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Expiration timestamp. When it is None it never expires

• metadata (object) – Optional. Metadata

EXAMPLE QUERY BODY

  {
      "name": "myapp-server",
      "expiration_timestamp": 12345234.4,
      "metadata": {"description": "key for test"}
  }

Response JSON Object

• id (string) – Key ID

• created_timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Created timestamp

• expiration_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Expiration timestamp

• is_expired (bool) – True if the key expired

• metadata (object) – Metadata

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

• key (string) – Secret Key

EXAMPLE RESPONSE

  {
      "id": "aeF32..",
      "key": "UB8gW9zxuV9D",
      "is_expired": false,
      "created_timestamp": 12341234.4,
      "expiration_timestamp": 12345234.4,
      "metadata": {"description": "key for test"}
  }

Errors:

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

Delete Service Account Key

DELETE accounts/service/keys/<str:key_id>/

Note

Authorized Roles: root, manager

This endpoint allows you to delete a service account key.

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

• db_id (string) – Optional. Database ID

• db_name (string) – Optional. Database Name

• email (email) – Email address

• password (string) – Password

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:

  • 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

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

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

• 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

• account (object) –

  Individual account

  Inner fields:

  • id (string) – Account ID

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

  • first_name (string) – First name

  • last_name (string) – Last name

  • email (email) – Email address

  • metadata (object) – Metadata

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"
      },
      "account": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@example.com",
          "role": "frontend",
          "metadata": {
              "previous_login_timestamp": 1707436148,
              "password_updated_timestamp": 1707736148
          }
      }
  }

Errors:

• AuthError with error name INCORRECT_PASSWORD if the password is incorrect

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

• db_id (string) – Optional. Database ID

• db_name (string) – Optional. Database Name

• name (string) – Service name

• password (string) – Named password for backward compatibility, but a key should be used

• 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

EXAMPLE QUERY BODY

  {
      "name": "myapp-web",
      "password": "my-service-key",
      "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:

  • 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

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

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

• 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

• account (object) –

  Service account

  Inner fields:

  • name (string) – Service name

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

  • metadata (object) – Metadata

EXAMPLE RESPONSE

  {
      "token": "eyJ0eX...",
      "org_id": "WEdZJsRxKvBrn2B_m6ZA",
      "role": "frontend",
      "refresh_token": "mW+k/K...",
      "frontend_user_id": 12358,
      "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"
      },
      "account": {
          "name": "myapp-web",
          "role": "frontend",
          "metadata": {
              "previous_login_timestamp": 1707436148,
              "password_updated_timestamp": 1707736148
          }
      }
  }

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

• db_id (string) – Optional. Database ID

• db_name (string) – Optional. Database Name

• refresh_token (string) – Refresh token

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:

  • 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

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

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

• 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

• account (object) –

  Individual account or Service account

  Inner fields:

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

  • first_name (string) – First name (only for individual account)

  • last_name (string) – Last name (only for individual account)

  • email (email) – Email address (only for individual account)

  • name (string) – Service name (only for service account)

  • metadata (object) – Metadata

EXAMPLE RESPONSE

  {
      "token": "eyJ0eX...",
      "org_id": "WEdZJsRxKvBrn2B_m6ZA",
      "role": "frontend",
      "refresh_token": "mW+k/K...",
      "frontend_user_id": 12358,
      "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"
      },
      "account": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@example.com",
          "role": "frontend",
          "metadata": {
              "previous_login_timestamp": 1707436148,
              "password_updated_timestamp": 1707736148
          }
      }
  }

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

Send Reset Password Email

POST accounts/individual/send-reset-password-email/

This endpoint will send a reset password code to the email address of an individual account.

All instruction to reset the password are inside the email.

Request JSON Object

• email (email) – Email address

• email_redirect_url (string) – Email redirect URL. The code and the code expiration will be added to the URL as query parameter, and then added to the body email.

EXAMPLE QUERY BODY

  {
      "email": "john@example.com",
      "email_redirect_url": "https://dashboard.crossingminds.com"
  }

Reset Password

POST accounts/individual/reset/

This endpoint allows you to set ot reset the password of an individual account using a code.

If you didn’t receive our email with the code, please see POST accounts/individual/send-reset-password-email/.

After password reset is successful to continue using our API you must call login,

please see POST login/individual/.

Request JSON Object

• code (string) – Reset password code

• email (email) – Email address

• new_password (string) – [min-length: 10] New password. Must contain at least one lowercase character, one uppercase character, one digit character and one non-alphanumeric character.

• code_expiration_timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Code expiration timestamp

EXAMPLE QUERY BODY

  {
      "code": "565nxzWOAe6rFebYq",
      "email": "john@example.com",
      "new_password": "6uZS1K66jqLl0gjge",
      "code_expiration_timestamp": 123123123.1
  }

Errors:

• AuthError with error name CODE_DOES_NOT_MATCH if the code is incorrect or CODE_EXPIRED

Verify login with JWT

POST login/jwt/

Verify login using JWT. Returns authentication context information.

Response JSON Object

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

• org_id (string) – Organization ID

• account (object) –

  Inner fields:

  • id (string) – Account ID

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

• database (object) –

  Optional.

  Inner fields:

  • id (string) – Database ID

  • 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

• 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

EXAMPLE RESPONSE

  {
      "org_id": "WEdZJsRxKvBrn2B_m6ZA",
      "frontend_user_id": 12358,
      "account": {
          "id": "WEdZJsRxKvBrn2B_m6ZA",
          "role": "frontend"
      },
      "database" : {
        "id": "wSSZQbPxKvBrk_n2B_m6ZA",
        "item_id_type": "uuid",
        "user_id_type": "uint32",
        "session_id_type": "uuid"
      }
  }

Delete Current Account

DELETE accounts/

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