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
] Rolefirst_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
] Rolename (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
] Rolefirst_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 existForbiddenError 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
] Rolename (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 existForbiddenError 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 asBearer
value in theAuthorization
header to authenticate your following requests, and keep therefresh_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
andfrontend_session_id
are set, the anonymous session will be automatically resolved to the given user, so callingPOST 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
] Rolerefresh_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:
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 asBearer
value in theAuthorization
header to authenticate your following requests, and keep therefresh_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
andfrontend_session_id
are set, the anonymous session will be automatically resolved to the given user, so callingPOST 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
] Rolerefresh_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/
¶
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 asBearer
value in theAuthorization
header, and keep the potentially newrefresh_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
] Rolerefresh_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 deletedAuthError with error name
INCORRECT_REFRESH_TOKEN
if the refresh token is invalidRefreshTokenExpired 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 existAuthError 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 existAuthError 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 existAuthError 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.