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.

Main documentation page: Authentication.

Request JSON Object

db_name (string) – Optional. Database Name
db_id (string) – Optional. Database ID
email (email) – Email address
password (string) – Password

EXAMPLE QUERY BODY¶

  {
      "email": "john@example.com",
      "password": "MyP@ssw0rd",
      "db_name": "Example DB name"
  }

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_name (string) – Optional. Database Name
db_id (string) – Optional. Database ID
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_name": "Example DB name",
      "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

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_name (string) – Optional. Database Name
db_id (string) – Optional. Database ID
refresh_token (string) – Refresh token

EXAMPLE NON DB_ID¶

  {
      "refresh_token": "mW+k/K..."
  }

EXAMPLE QUERY BODY¶

  {
      "refresh_token": "mW+k/K...",
      "db_name": "Example DB name"
  }

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.

Authentication Flow¶

List All Accounts¶

Create Individual Account¶

Delete Individual Account¶

Partial Update Individual Account¶

Create Service Account¶

Delete Service Account¶

Create Service Account Key¶

Delete Service Account Key¶

Login as Individual Account¶

Login as Service Account¶

Login as Root¶

Renew Login with Refresh Token¶

Send Reset Password Email¶

Reset Password¶

Verify login with JWT¶

Delete Current Account¶