NAV
cURL Typescript

Start

This documentation describes the all functionality available through the HTTP REST api and the available low level clients that wraps this functionality for different programming languages.

All calls to Nblocks are encrypted over HTTPS.

If you wish to go back to the high level and plug-n-play documentation click here

Authentication

How it works

Request example with api key

const client = new NblocksClient(YOUR_APP_API_KEY);
await new client.some.cool.function();
curl --request GET 'https://someapi.com/endpoint' \
--header 'x-api-key: YOUR_APP_API_KEY'

All calls to Nblocks apis requires you to authorize yourself as a valid app, either with your unique App ID or more commonly your secret API key. You should have received these keys upon registration. The apis expect you to authorize each call by including your api key in the HTTP headers.

x-api-key: YOUR_APP_API_KEY

This should not be confused with your users authenticating. When they login into your app they authenticate with their own credentails using a Oauth 2.0 flow.

Registrating for a new app profile

npx @nebulr-group/nblocks-cli create-app

The NPX tool will create a new folder and place a .env file containing your Nblocks API key and download a copy of your app profile into a file app-configuration.json. Use this API key from the env file and the App ID from your app profile to start calling our APIs.

App Profile

As the developer, the App profile is your entrypoint to Nblocks. This is your unique set of settings to tailor the Nblocks experience. You can have several different Profiles, e.g. one for production and one for testing. This helps organize and separate configurations from different stages in your development process.

Get app profile

Request example

const response = await client.config.getAppProfile();
curl --request GET 'https://account-api.nebulr-core.com/app' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "id": "624c14cc0c01e70033356282",
    "name": "My app",
    "domain": "MY_APP",
    "apiUrl": "http://localhost:3000",
    "uiUrl": "http://localhost:8100",
    "webhookUrl": "http://api.example.com/webhook"
    "stripeEnabled": false,
    "passkeysEnabled": true,
    "azureMarketplaceEnabled": false,
    "googleSsoEnabled": false,
    "azureAdSsoEnabled": true,
    "onboardingFlow": "B2B",
    "cloudViews": true,
    "redirectUris": ["http://localhost:8080/auth/oauth-callback"],
    "defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
    "defaultRole": "OWNER",
    "roles": {
        "OWNER": [
            "AUTHENTICATED",
            "TENANT_READ",
            "TENANT_WRITE",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "TAG_WRITE",
            "USER_READ",
            "USER_WRITE",
            "GROUP_WRITE",
            "GROUP_READ",
            "ASSIGNEES_WRITE",
            "SETTINGS_READ",
            "SETTINGS_WRITE"
        ],
        "ADMIN": [
            "AUTHENTICATED",
            "TENANT_READ",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "TAG_WRITE",
            "USER_READ",
            "USER_WRITE",
            "GROUP_WRITE",
            "GROUP_READ",
            "ASSIGNEES_WRITE",
            "SETTINGS_READ",
            "SETTINGS_WRITE"
        ],
        "MANAGER": [
            "AUTHENTICATED",
            "TENANT_READ",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "USER_READ",
            "GROUP_READ",
            "SETTINGS_READ"
        ],
    },
    "businessModel": {
        "taxes": [
            {
            "region": "SE",
            "name": "VAT",
            "percentage": 25
            }
        ],
        "plans": [
            {
            "name": "ESSENTIAL",
            "prices": [
                {
                "region": "SE",
                "amount": 500,
                "currency": "SEK",
                "recurrenceInterval": "month"
                },
                {
                "region": "DE",
                "amount": 50,
                "currency": "EUR",
                "recurrenceInterval": "month"
                }
            ]
            },
            {
            "name": "TEAM",
            "trialDays": 14,
            "prices": [
                {
                "region": "SE",
                "amount": 1000,
                "currency": "SEK",
                "recurrenceInterval": "month"
                },
                {
                "region": "DE",
                "amount": 100,
                "currency": "EUR",
                "recurrenceInterval": "month"
                }
            ]
            }
        ]
    },
    "logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
    "websiteUrl": "http://localhost",
    "privacyPolicyUrl": "",
    "termsOfServiceUrl": ""
}

Gets the complete App model of your app. The app is your top most entity and holds all configurations for how your App interacts with the platform in any sub call. Use this response data to alter your model and push back.

HTTP Request

GET https://account-api.nebulr-core.com/app

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Response

HTTP 200

Your App profile model

Update app profile

Request example

const response = await client.config.updateAppProfile({logo: "https://www.example.com/another_logo.png"});
curl --request PUT 'https://account-api.nebulr-core.com/app' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "logo": "https://www.example.com/another_logo.png"
}'

Response example:

{
    "id": "624c14cc0c01e70033356282",
    "name": "My app",
    "domain": "MY_APP",
    "apiUrl": "http://localhost:3000",
    "uiUrl": "http://localhost:8100",
    "webhookUrl": "http://api.example.com/webhook"
    "stripeEnabled": false,
    "passkeysEnabled": true,
    "azureMarketplaceEnabled": false,
    "googleSsoEnabled": false,
    "azureAdSsoEnabled": true,
    "onboardingFlow": "B2B",
    "cloudViews": true,
    "redirectUris": ["http://localhost:8080/auth/oauth-callback"],
    "defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
    "defaultRole": "OWNER",
    "roles": {
        "OWNER": [
            "AUTHENTICATED",
            "TENANT_READ",
            "TENANT_WRITE",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "TAG_WRITE",
            "USER_READ",
            "USER_WRITE",
            "GROUP_WRITE",
            "GROUP_READ",
            "ASSIGNEES_WRITE",
            "SETTINGS_READ",
            "SETTINGS_WRITE"
        ],
        "ADMIN": [
            "AUTHENTICATED",
            "TENANT_READ",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "TAG_WRITE",
            "USER_READ",
            "USER_WRITE",
            "GROUP_WRITE",
            "GROUP_READ",
            "ASSIGNEES_WRITE",
            "SETTINGS_READ",
            "SETTINGS_WRITE"
        ],
        "MANAGER": [
            "AUTHENTICATED",
            "TENANT_READ",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "USER_READ",
            "GROUP_READ",
            "SETTINGS_READ"
        ],
    },
    "businessModel": {
        "taxes": [
            {
            "region": "SE",
            "name": "VAT",
            "percentage": 25
            }
        ],
        "plans": [
            {
            "name": "ESSENTIAL",
            "prices": [
                {
                "region": "SE",
                "amount": 500,
                "currency": "SEK",
                "recurrenceInterval": "month"
                },
                {
                "region": "DE",
                "amount": 50,
                "currency": "EUR",
                "recurrenceInterval": "month"
                }
            ]
            },
            {
            "name": "TEAM",
            "trialDays": 14,
            "prices": [
                {
                "region": "SE",
                "amount": 1000,
                "currency": "SEK",
                "recurrenceInterval": "month"
                },
                {
                "region": "DE",
                "amount": 100,
                "currency": "EUR",
                "recurrenceInterval": "month"
                }
            ]
            }
        ]
    },
    "logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
    "websiteUrl": "http://localhost",
    "privacyPolicyUrl": "",
    "termsOfServiceUrl": ""
}

You can update the app with the same JSON you got from Get app model or just provide the field you want to update

HTTP Request

PUT https://account-api.nebulr-core.com/app

Body Parameters

Parameter Type Required Description
name string Optional Name of the app
apiUrl string Optional URL to your api (to receive webhooks etc).
defaultRole string Optional Default user role
uiUrl string Optional URL to your frontend app (for onboarding redirects etc).
webhookUrl string Optional Enable webhook and events to be sent to this url
roles Record Optional All user roles and their granted privileges
businessModel BusinessModel Optional The business model defines what plans are available to subscribe to and what taxes applies.
logo string Optional URL to your logo
websiteUrl string Optional URL to your website or landing page. E.g. Branded emails will link to this URL, checkout process will redirect to /payment-success and /payment-cancel
privacyPolicyUrl string Optional URL to a page on your website containing a Privacy policy for your app users. E.g. checkout process will link to this url.
termsOfServiceUrl string Optional URL to a page on your website containing a Terms of service for your app users. E.g. checkout process will link to this url.
emailSenderName string Optional Emails sent from Nblocks will have this sender name
emailSenderEmail string Optional Emails sent from Nblocks will have this sender email. You'll have to verify this email before
onboardingFlow OnboardingFlow Optional Configure how users will be onboarded
cloudViews boolean Optional Toggle this to true if you want to use a UI provided by NBlocks instead of your own
redirectUris string[] Optional Allowed redirect uris
defaultCallbackUri string Optional Default handover/callback uri used by Nblocks

Response

HTTP 200

Your App profile model

Update credentials

Request example

const response = await client.config.updateCredentials({
    googleClientId: "XXXXXXX",
    googleClientSecret: "XXXXXXX"
});
curl --request PUT 'https://account-api.nebulr-core.com/app/credentials' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "googleClientId": "XXXXXXX",
    "googleClientSecret": "XXXXXXX"
}'

Store sensitive credentials for your app so NBlocks can authorize with 3d party services on your behalf.

These credentials are never outputted back again

E.g. Stripe integration, social login providers like Google, Facebook, Github etc.

HTTP Request

PUT https://account-api.nebulr-core.com/app/credentials

Body Parameters

Parameter Type Required Description
stripeSecretKey string Optional Stripe integration, secret key
stripePublicKey string Optional Stripe integration, public key
microsoftAzureMarketplaceClientId string Optional Microsoft Azure Marketplace integration App
microsoftAzureMarketplaceClientSecret string Optional Microsoft Azure Marketplace integration App
microsoftAzureMarketplaceTenantId string Optional Microsoft Azure Marketplace integration App
googleClientId string Optional Google social login
googleClientSecret string Optional Google social login
githubClientId string Optional Gitlab social login
githubClientSecret string Optional Gitlab social login
facebookAppId string Optional Facebook social login
facebookAppSecret string Optional Facebook social login
microsoftAzureADClientId string Optional MS Azure AD SSO
microsoftAzureADClientSecret string Optional MS Azure AD SSO
microsoftAzureADTenantId string Optional MS Azure AD SSO

Response

HTTP 200

Branding

You can change the looks of Nblocks by changing your app's branding.

Nblocks supports these different kinds of branding.

Set custom email template

Request example

TBD
curl --request PUT 'https://communication-api.nebulr-core.com/template/SIGNUP' \
--header 'x-api-key: YOUR_APP_API_KEY'
--data-raw '{
    "type": "SIGNUP", 
    "testRecipient": "john@doe.com", 
    "content": "<h1>Signup</h1><a href=\"{{ctaUrl}}\">Click here</a>"
}'

Overriding one of the pre defined templates can be done easily. When you override a template, Nblocks will use this content for all languages.

Templates Description
RESET-PASSWORD Sent to the user when the user requests to set a new password
SIGNUP Sent when a user sign up for a new tenant
INVITE_NEW Sent when a new user is invited to a tenant
INVITE_EXISTING Sent when an existing user of other tenants are invited to a tenant
PAYMENT_FAILURE Sent to the tenant owner if in case of any subscription payment failures
BASE This template is used when you send transactional emails yourself through the api.

The HTML content supports variables that are injected when rendering the template. Except for the ctaUrl variable, which contains a unique link if the mail asks the user to perform an action, these are not required and can be considered just as helpers. Variables in themplates, use <h1>{{variable}}</h1> to inject it in the content html.

Variable Example Description
appName My app Your app name
appLogo https://url-to-logo.png Your app logo url
appUrl https://url-to-app.com A url to your app frontend
emailTitle Reset your password The title of the email. Comes from Nblocks standard texts
emailBody To reset your password, please click the button... The content of the email. Comes from Nblocks standard texts
ctaTitle Reset password The Call-to-action button title. Comes from Nblocks standard texts
ctaUrl https://unique-link... The Call-to-action button link. A unique link relevant to this email
fallBackButtonText Button not working? Click the li... A title to a fallback link displayed under the CTA button for older email clients
currentYear 2023 Current year

HTTP Request

PUT https://communication-api.nebulr-core.com/template/:templateName

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

URL Parameters

Parameter Description
templateName Any of the available template names listed above

Body Parameters

Parameter Type Required Description
type string Yes Any of the available template names listed above
testRecipient string No If provided, Nblocks will send a test email with the updated template
content string Yes The template content in HTML

Response

HTTP 200

Get custom email template

Request example

TBD
curl --request GET 'https://communication-api.nebulr-core.com/template/SIGNUP' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "type": "SIGNUP",
    "content": "<h1>Signup</h1><a href=\"{{ctaUrl}}\">Click here</a>"
}

Get a custom email template

HTTP Request

GET https://communication-api.nebulr-core.com/template/:templateName

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

URL Parameters

Parameter Description
templateName Any of the available template names listed in set custom email template

Response

HTTP 200

Parameter Type Description
type string The template name
content string The template content in HTML

Delete custom email template

Request example

TBD
curl --request DELETE 'https://communication-api.nebulr-core.com/template/SIGNUP' \
--header 'x-api-key: YOUR_APP_API_KEY'

Deleting a custom template will restore Nblocks default template.

HTTP Request

DELETE https://communication-api.nebulr-core.com/template/:templateName

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

URL Parameters

Parameter Description
templateName Any of the available template names listed in set custom email template

Response

HTTP 200

Set custom CSS

Request example

TBD
curl --request POST 'https://backendless.nblocks.cloud/brand/css' \
--header 'x-api-key: YOUR_APP_API_KEY'
--data-raw '{
    "content": "html,body { background-color: red !important; }"
}'

The CSS is used by Nblocks Cloud views, like Nblocks Login and User Management portal. Use the example css as a base to start set your own brand.

HTTP Request

POST https://backendless.nblocks.cloud/brand/css

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Body Parameters

Parameter Type Required Description
content string Yes The CSS content

Response

HTTP 200

Get your custom CSS

Request example

TBD
curl --request GET 'https://backendless.nblocks.cloud/brand/css' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "content": "html,body { background-color: red !important; }"
}

The CSS is used by Nblocks Cloud views, like Nblocks Login and User Management portal.

HTTP Request

GET https://backendless.nblocks.cloud/brand/css

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Response

HTTP 200

Parameter Type Description
content string The CSS content

Set custom Translations

Request example

TBD
curl --request POST 'https://backendless.nblocks.cloud/brand/translations' \
--header 'x-api-key: YOUR_APP_API_KEY'
--data-raw '{
    "Login": "Log in",
    "Email address": "Email"
}'

The translations are used by Nblocks Cloud views, like Nblocks Login and User Management portal. Use this template to understand what translations can be changed.

HTTP Request

POST https://backendless.nblocks.cloud/brand/translations

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Body Parameters

Your translations content as JSON. See example

Response

HTTP 200

Get your custom Translations

Request example

TBD
curl --request GET 'https://backendless.nblocks.cloud/brand/translations' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "Login": "Log in",
    "Email address": "Email"
}

The translations are used by Nblocks Cloud views, like Nblocks Login and User Management portal.

HTTP Request

GET https://backendless.nblocks.cloud/brand/translations

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Response

HTTP 200

Your translations content as JSON

User authentication

User authentication is done using Nblocks Auth Service that supports Oauth 2.0 / OpenID Connect and tokens are issued as JWTs.

At a glance, the authentication process looks like this:

  1. You initiate the login process by redirecting the user to the /authorize endpoint (or the simpler shorthand /login and /signup endpoints).
  2. User is pulled through an authentication process provided by Nblocks with cloud views.
  3. Once the user is authenticated and has selected the tenant to access the user is redirect back to your app with a code.
  4. You make a call to the /token endpoint with this code to exchange it for access tokens and user profile information (openid).
  5. You can verify that the tokens are valid and safe to trust by using the public keys available from the /.well-known endpoint.
  6. You will be able to refresh the tokens using the /token endpoint to obtain up to date access and profile information.

Authorize

Start the Oauth 2.0 user login flow by redirecting the user to the /authorize endpoint. The user will be able to choose login method and after authentication process get back to your app with an auth code that you can exchange for access and openid tokens.

HTTP Request

GET https://auth.nblocks.cloud/authorize

Query Parameters

Parameter Type Required Description
client_id string Required Your app id
response_type string Required What kind of tokens will be generated. We support code
redirect_uri string Required A target URI where the authenticated user will be redirected to together with tokens. Must be a valid URI in your App redirectUris
scope string Required Any or all of the following: openid, profile, email, address, phone, onboarding, tenant
state string Optional This can be used to resume a state in your app. The state will be available in the response code
force_federation string Optional If you want to force a certain federated login flow instead of letting the user choose during login. Possible values ms-azure-ad and google
signup boolean Optional If you want to initiate a signup instead of the default login flow for the user.

Get tokens

Request example exchanging code for tokens

const response = await client.auth.getTokens({code: "XXXX"});
curl --request POST 'https://auth.nblocks.cloud/token' \
--data-raw '{
    client_id: "YOUR_APP_ID", grant_type: "authorization_code", code: "XXXX", "redirect_uri": "http://localhost:8080/auth/oauth-callback"
}'

Request example exchanging refresh token for tokens

const response = await client.auth.refreshTokens({refreshToken: "XXXX"});
curl --request POST 'https://auth.nblocks.cloud/token' \
--data-raw '{
    client_id: "YOUR_APP_ID", grant_type: "refresh_token", refresh_token: "XXXX"
}'

Response example:

{
    "access_token": "XXXX",
    "refresh_token": "XXXX",
    "token_type": "Bearer",
    "expires_in": "XXXX",
    "id_token": "XXXX"
}

Get new tokens using an authorization code from a user just completed authentication or by using the refresh token that was issued to a logged in user before. This endpoints serves both cases.

HTTP Request

POST https://auth.nblocks.cloud/token

Body Parameters

Parameter Type Required Description
client_id string Required Your app id
grant_type string Required authorization_code or refresh_token
code string Required for authorization_code The code you recieved from the authenticated user.
redirect_uri string Required for authorization_code A target URI where the authenticated user will be redirected to together with tokens. Must be a valid URI in your App redirectUris
refresh_token string Required for refresh_token The refresh token that was issued when getting the tokens before

Response

HTTP 200

Tokens response

Short hand authorize

Shorthand endpoints exists so you can use them with less parameters using sensible defaults. Use the simpler short hand endpoint /url/login to initiate the login flow. The Nblocks will collect your default config and issue the Oauth 2.0 flow.

HTTP Request

GET https://auth.nblocks.cloud/url/login/:YOUR_APP_ID

URL Parameters

Parameter Description
YOUR_APP_ID The ID of your app

Query Parameters

Parameter Type Required Description
redirectUri string Optional A target URI where the authenticated user will be redirected to together with tokens. The default value is your App defaultCallbackUri.
state string Optional This can be used to resume a state in your app. The state will be available in the response code
forceFederation string Optional If you want to force a certain federated login flow instead of letting the user choose during login. We support ms-azure-ad

Short hand signup

Shorthand endpoints exists so you can use them with less parameters using sensible defaults. Use the simpler short hand endpoint /url/signup to initiate the signup flow. The Nblocks will collect your default config and issue the Oauth 2.0 flow.

HTTP Request

GET https://auth.nblocks.cloud/url/signup/:YOUR_APP_ID

URL Parameters

Parameter Description
YOUR_APP_ID The ID of your app

Query Parameters

Parameter Type Required Description
redirectUri string Optional A target URI where the authenticated user will be redirected to together with tokens. The default value is your App defaultCallbackUri.
state string Optional This can be used to resume a state in your app. The state will be available in the response code
forceFederation string Optional If you want to force a certain federated login flow instead of letting the user choose during login. We support ms-azure-ad

Shorthand get tokens

Request example exchanging code for tokens

const response = await client.auth.getTokens({code: "XXXX"});
curl --request POST 'https://auth.nblocks.cloud/token/code/YOUR_APP_ID' \
--data-raw '{
    "code": "XXXX"
}'

Request example exchanging refresh token for tokens

const response = await client.auth.refreshTokens({refreshToken: "XXXX"});
curl --request POST 'https://auth.nblocks.cloud/token/refresh/YOUR_APP_ID' \
--data-raw '{
    "refreshToken": "XXXX"
}'

Response example:

{
    "access_token": "XXXX",
    "refresh_token": "XXXX",
    "token_type": "Bearer",
    "expires_in": "XXXX",
    "id_token": "XXXX",
    "user_profile": {
        "sub": "63d25a9e0796d40008680f9a",
        "name": "John Doe",
        "family_name": "Doe",
        "given_name": "John",
        "preferred_username": "john@example.com",
        "locale": "en",
        "email": "john@example.com",
        "email_verified": true,
        "onboarded": true,
        "tenant_id": "63d25a9e0796d40008680f96",
        "tenant_name": "Johns Family",
        "tenant_locale": "en",
        "tenant_logo": "",
    }
}

Shorthand endpoints exists so you can use them with less parameters using sensible defaults. Get new tokens using an authorization code from a user just completed authentication or by using the refresh token that was issued to a logged in user before. This endpoints serves both cases.

HTTP Request

POST https://auth.nblocks.cloud/token/:grantType/:YOUR_APP_ID

URL Parameters

Parameter Description
grantType code or refresh
YOUR_APP_ID The ID of your app

Body Parameters

Parameter Type Required Description
code string Required for code grant The code you recieved from the authenticated user.
refreshToken string Required for refresh grant The refresh token that was issued when getting the tokens before
redirectUri string Optional for code grant A target URI where the authenticated user will be redirected to together with tokens. The default value is your App defaultCallbackUri.

Response

HTTP 200

Tokens response

Handover code

Request example getting handover code

TBD
curl --request POST 'https://auth.nblocks.cloud/handover/code/YOUR_APP_ID' \
--data-raw '{
    "accessToken": "XXXX"
}'

Response example:

{
    "code": "XXXX"
}

This endpoint returns a handover code which is used when redirecting to or displaying Nblocks hosted views and user interactions. The code is shortlived and should be consumed with a follow up call to which interaction you want to display for the user.

HTTP Request

POST https://auth.nblocks.cloud/handover/code/:YOUR_APP_ID

URL Parameters

Parameter Description
YOUR_APP_ID The ID of your app

Body Parameters

Parameter Type Required Description
accessToken string Yes A valid user access token

Response

HTTP 200

Parameter Type Description
code string A shortlived unique token

Users

These are your app's users. We call them Tenant users since, they belong to a tenant. But they can use the same credentials to access multiple tenants should their username exists in several places.

User management portal - Users

This endpoint renders Nblocks hosted user management views for listing and managing users. Redirect the user agent or embedd this url into an iframe to render the view. Users will be able to list and invite other users to the same tenant. See Handover code for how to obtain the code parameter required for this call.

HTTP Request

GET https://backendless.nblocks.cloud/user-management-portal/users?code=XXXX

URL Parameters

Parameter Description
code The code recieved from handover endpoint

Tenants

A tenant represents a customers workspace in your app. These are isolated data silos of team members, settings, and application data.

List all tenants

Request example

const response = await client.tenants.list();
curl --request GET 'https://account-api.nebulr-core.com/tenant' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "606b00a61679e20008a5654d",
        "plan": "TEAM",
        "mfa": false,
        "locale": "en",
        "name": "John Inc",
        "logo": "",
        "metadata": {},
        "createdAt": "2021-04-05T12:20:54.890Z",
        "paymentsEnabled": false,
        "paymentsRequired": true,
        "onboarded": true
    },
    {
        "id": "605dd819e8fd3e00086cc552",
        "plan": "ESSENTIAL",
        "mfa": false,
        "locale": "en",
        "name": "Dave Ltd",
        "logo": "",
        "metadata": {},
        "createdAt": "2021-03-26T12:48:25.187Z",
        "paymentsEnabled": false,
        "paymentsRequired": true,
        "onboarded": true
    }
]

Lists all tenants in your app. Each tenant will have their own sets of users.

HTTP Request

GET https://account-api.nebulr-core.com/tenant

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Response

HTTP 200

A list of Tenant models

Get tenant by id

Request example

const response = await client.tenant('606b00a61679e20008a5654d').get();
curl --request GET 'https://account-api.nebulr-core.com/tenant/byId/606b00a61679e20008a5654d' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "id": "606b00a61679e20008a5654d",
    "plan": "TEAM",
    "mfa": false,
    "locale": "en",
    "name": "John Inc",
    "logo": "",
    "metadata": {},
    "createdAt": "2021-04-05T12:20:54.890Z",
    "paymentsEnabled": false,
    "paymentsRequired": true,
    "onboarded": true
}

Get a single tenant in your app

HTTP Request

GET https://account-api.nebulr-core.com/tenant/byId/:TENANT_ID

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

URL Parameters

Parameter Description
TENANT_ID The ID of the tenant

Response

HTTP 200

Tenant model

Create new tenant

Request example

const response = await client.tenants.create(
    {
        name: "New Company Ltd",
        plan: "TEAM",
        owner: {
            email: "john@example.com", 
            firstName: "John", 
            lastName: "Doe"
            },
        metadata: {
            VIP: "true"
        }
    });
curl --request POST 'https://account-api.nebulr-core.com/tenant' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "name": "New Company Ltd","plan": "TEAM", "owner": {"email": "john@example.com", "firstName": "John", "lastName": "Doe"},"metadata": {"VIP": "true"}
    }'

Response example:

{
    "id": "606b00a61679e20008a5654d",
    "plan": "TEAM",
    "mfa": false,
    "locale": "en",
    "name": "John Inc",
    "logo": "",
    "metadata": {},
    "createdAt": "2021-04-05T12:20:54.890Z",
    "paymentsEnabled": false,
    "paymentsRequired": true,
    "onboarded": true
}

Creates a new tenant with an initial user that is regarded as the tenant owner.

HTTP Request

POST https://account-api.nebulr-core.com/tenant

Body Parameters

Parameter Type Required Description
owner TenantOwner Required A user will need to be assigned as an owner to this tenant. Either reused if the user already exist or a new user will be created. The user will be onboarded automatically. See below
name string Optional Name of the tenant. Can also be set by tenant owner during onboarding
plan string Optional The plan must be present in the configured App business model
logo string Optional A URI to a logo. Can also be set by tenant owner during onboarding
metadata Record Optional Store metadata for your own business logic that will be returned in every Tenant response. This data will never be outputted to the end user

TenantOwner

Parameter Type Required Description
email string Required A user will need to be assigned as an owner to this tenant. Either reused if the user already exist or a new user will be created. The user will be onboarded automatically
firstName string Optional The first name. Can also be set by tenant owner during onboarding
lastName string Optional The last name. Can also be set by tenant owner during onboarding
muteNotifications boolean Optional Set this variable to true if you don't wish to send out any invitation/notifications to the new user

Response

HTTP 201

Tenant model

Update tenant

Request example

const response = await client.tenant('606b00a61679e20008a5654d').update(
    {
        logo: "http://path/to/logo.png",
        locale: "en"
    });
curl --request PUT 'https://account-api.nebulr-core.com/tenant/606b00a61679e20008a5654d' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "logo": "http://path/to/logo.png","locale": "en"
    }'

Response example:

{
    "id": "606b00a61679e20008a5654d",
    "plan": "TEAM",
    "mfa": false,
    "locale": "en",
    "name": "John Inc",
    "logo": "",
    "metadata": {},
    "createdAt": "2021-04-05T12:20:54.890Z",
    "paymentsEnabled": false,
    "paymentsRequired": true,
    "onboarded": true
}

Update an existing tenant.

HTTP Request

PUT https://account-api.nebulr-core.com/tenant/TENANT_ID

Body Parameters

Parameter Type Required Description
name string Optional Name of the tenant.
locale string Optional The default locale / lang code for all users in this tenant (ISO_639-1 format). This property will set the i18n for all platform emails
plan string Optional The plan must be present in the configured App business model
logo string Optional A URI to a logo.
mfa boolean Optional Require users to login with MFA/2FA
metadata Record Optional Store metadata for your own business logic that will be returned in every Tenant response. This data will never be outputted to the end user

Response

HTTP 200

Tenant model

Feature flags

Feature flags allows you to conditionally give access to or show / hide features or content to your users.

To use feature flags you must first create Flags and link them with Segments. Then you can start making Evaluation calls where you provide the current Context and the API will take care of matching the context with the segments and returns if the flag is enabled or not.

Some use cases for feature flags are:

Evaluate a flag

Request example

TBD
curl --request POST 'https://backendless.nblocks.cloud/flags/evaluate/605b603cfeb49f00082686b6/iphone-feature' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "context": {
        "device": {
            "key": "iphone"
        },
        "user": {
            "key": "fooBar"
        }
    },
    "accessToken": "XXXX"
}'

Response example:

{
    "enabled": true
}

Evaluate a single flag by providing context or user access token.

You can send whatever context information you want to the evaluation api. But we've simplified it using a base structure so you can build the segment targets in Nblocks Admin more easily.

The context object contains three areas, user, org and device.

Each one of them contains the property key. You can assign any value to this property. You can also assign any values you want to the other properties. When building the segment targets you can define is the value should be equal (==), contain, beginWith or endWith the value. Structure of the body that can be sent to /flags/evaluate

Providing the access token will automatically resolve all values for user and org so you don't have to.

HTTP Request

POST https://backendless.nblocks.cloud/flags/evaluate/APP_ID/FLAG_KEY

URL Parameters

Parameter Description
APP_ID Your app id
FLAG_ID The ID of the flag

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Body Parameters

Parameter Type Required Description
context Context No A context object
accessToken string No A user token

Response

HTTP 200

Parameter Type Description
enabled boolean Evaluation result. If the flag is enabled or not. Use this to conditionally render the feature

Evaluate flags in bulk

Request example

TBD
curl --request POST 'https://backendless.nblocks.cloud/flags/bulkEvaluate/605b603cfeb49f00082686b6' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "context": {
        "device": {
            "key": "iphone"
        },
        "user": {
            "key": "fooBar"
        }
    },
    "accessToken": "XXXX"
}'

Response example:

{
    "flags": [
        {
            "flag": "iphone-feature",
            "evaluation": {
                "enabled": true
            }
        }
    ]
}

Evaluate all flags in bulk by providing context or user access token. Use this to limit the amount of individual flag evaluation calls

You can send whatever context information you want to the evaluation api. But we've simplified it using a base structure so you can build the segment targets in Nblocks Admin more easily.

The context object contains three areas, user, org and device.

Each one of them contains the property key. You can assign any value to this property. You can also assign any values you want to the other properties. When building the segment targets you can define is the value should be equal (==), contain, beginWith or endWith the value. Structure of the body that can be sent to /flags/evaluate

Providing the access token will automatically resolve all values for user and org so you don't have to.

HTTP Request

POST https://backendless.nblocks.cloud/flags/bulkEvaluate/APP_ID

URL Parameters

Parameter Description
APP_ID Your app id

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Body Parameters

Parameter Type Required Description
context Context No A context object
accessToken string No A user token

Response

HTTP 200

Parameter Type Description
flags EvaluatedFlag[] Individual evaluation response for each flag

EvaluatedFlag

Parameter Type Description
flag string Flag key
evaluation EvaluationResponse The evaluation response

EvaluationResponse

Parameter Type Description
enabled boolean If the flag is enabled or not. Use this to conditionally render the feature

List segments

Request example

TBD
curl --request GET 'https://admin-api.nblocks.cloud/flags/segment' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "64c63e7adaf20f0008e71b20",
        "key": "iphones",
        "description": "This segment targets iPhones",
        "targets": [
            {
                "device": {
                    "key": {
                        "operator": "contains",
                        "value": "iphone"
                    }
                }
            }
        ]
    },
    {
        "id": "64c6400fdaf20f0008e71b25",
        "key": "admins",
        "description": "This segment targets admins",
        "targets": [
            {
                "user": {
                    "role": {
                        "operator": "eq",
                        "value": "ADMIN"
                    }
                }
            }
        ]
    }
]

List all segments

HTTP Request

GET https://admin-api.nblocks.cloud/flags/segment

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Response

HTTP 200

List of Segment

Create a segment

Request example

TBD
curl --request POST 'https://admin-api.nblocks.cloud/flags/segment' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "key": "admins",
    "description": "This segment targets admins",
    "targets": [
        {
            "user": {
                "role": {
                    "operator": "eq",
                    "value": "ADMIN"
                }
            }
        }
    ]
}'

Response example:

{
    "id": "64c6400fdaf20f0008e71b25",
    "key": "admins",
    "description": "This segment targets admins",
    "targets": [
        {
            "user": {
                "role": {
                    "operator": "eq",
                    "value": "ADMIN"
                }
            }
        }
    ]
}

Create a segment

HTTP Request

POST https://admin-api.nblocks.cloud/flags/segment

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Body Parameters

Parameter Type Required Description
key string Yes A unique key for this segment
description string No Optional description
targets Target[] No The targets to match

Response

HTTP 200

Segment

Update a segment

Request example

TBD
curl --request PUT 'https://admin-api.nblocks.cloud/flags/segment/64c6400fdaf20f0008e71b25' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "description": "Updated description",
}'

Response example:

{
    "id": "64c6400fdaf20f0008e71b25",
    "key": "admins",
    "description": "Updated description",
    "targets": [
        {
            "user": {
                "role": {
                    "operator": "eq",
                    "value": "ADMIN"
                }
            }
        }
    ]
}

Update an existing segment

HTTP Request

PUT https://admin-api.nblocks.cloud/flags/segment/SEGMENT_ID

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

URL Parameters

Parameter Description
SEGMENT_ID The ID of the segment

Body Parameters

Parameter Type Required Description
key string No A unique key for this segment
description string No Optional description
targets Target[] No The targets to match

Response

HTTP 200

Segment

Delete a segment

Request example

TBD
curl --request DELETE 'https://admin-api.nblocks.cloud/flags/segment/64c6400fdaf20f0008e71b25' \
--header 'x-api-key: YOUR_APP_API_KEY'

Delete an existing segment. Deleting a segment will also remove the relationship with affected flags.

HTTP Request

PUT https://admin-api.nblocks.cloud/flags/segment/SEGMENT_ID

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

URL Parameters

Parameter Description
SEGMENT_ID The ID of the segment

Response

HTTP 200

List flags

Request example

TBD
curl --request GET 'https://admin-api.nblocks.cloud/flags/flags' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "64c64cfb47418500082f60b5",
        "key": "iphone-feature",
        "description": "A feature for iPhones",
        "defaultValue": false,
        "segments": [
            {
                "id": "64c63e7adaf20f0008e71b20",
                "key": "iphones",
                "description": "This segment targets iPhones",
                "targets": [
                    {
                        "device": {
                            "key": "iphone"
                        }
                    }
                ]
            }
        ],
        "targetValue": true,
        "enabled": true
    }
]

List all segments

HTTP Request

GET https://admin-api.nblocks.cloud/flags/segment

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Response

HTTP 200

List of Flag

Create a flag

Request example

TBD
curl --request POST 'https://admin-api.nblocks.cloud/flags/flag' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "key": "iphone-feature",
    "description": "A feature for iPhones",
    "defaultValue": false,
    "segments": [
        "64c63e7adaf20f0008e71b20"
    ],
    "targetValue": true,
    "enabled": true
}'

Response example:

{
    "id": "64c64cfb47418500082f60b5",
    "key": "iphone-feature",
    "description": "A feature for iPhones",
    "defaultValue": false,
    "segments": [
        {
            "id": "64c63e7adaf20f0008e71b20",
            "key": "iphones",
            "description": "This segment targets iPhones",
            "targets": [
                {
                    "device": {
                        "key": "iphone"
                    }
                }
            ]
        }
    ],
    "targetValue": true,
    "enabled": true
}

Create a flag

HTTP Request

POST https://admin-api.nblocks.cloud/flags/flag

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

Body Parameters

Parameter Type Required Description
key string Yes A unique key for this flag
description string No Optional description
defaultValue boolean No The value to return if no segment was found or matched
segments string[] No List of IDs of the segments which should be matched
targetValue boolean No The value to return of a segment was matched
enabled boolean No Active state. Only enabled flags are available for evaluation. Otherwise evaluation falls back to false.

Response

HTTP 200

Flag

Update a flag

Request example

TBD
curl --request PUT 'https://admin-api.nblocks.cloud/flags/flag/64c6400fdaf20f0008e71b25' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "enabled": false,
}'

Response example:

{
    "id": "64c64cfb47418500082f60b5",
    "key": "iphone-feature",
    "description": "A feature for iPhones",
    "defaultValue": false,
    "segments": [
        {
            "id": "64c63e7adaf20f0008e71b20",
            "key": "iphones",
            "description": "This segment targets iPhones",
            "targets": [
                {
                    "device": {
                        "key": "iphone"
                    }
                }
            ]
        }
    ],
    "targetValue": true,
    "enabled": false
}

Update an existing flag

HTTP Request

PUT https://admin-api.nblocks.cloud/flags/segment/FLAG_ID

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

URL Parameters

Parameter Description
FLAG_ID The ID of the flag

Body Parameters

Parameter Type Required Description
key string No A unique key for this flag
description string No Optional description
defaultValue boolean No The value to return if no segment was found or matched
segments string[] No List of IDs of the segments which should be matched
targetValue boolean No The value to return of a segment was matched
enabled boolean No Active state. Only enabled flags are available for evaluation. Otherwise evaluation falls back to false.

Response

HTTP 200

Flag

Delete a flag

Request example

TBD
curl --request DELETE 'https://admin-api.nblocks.cloud/flags/flag/64c6400fdaf20f0008e71b25' \
--header 'x-api-key: YOUR_APP_API_KEY'

Delete an existing flag.

HTTP Request

PUT https://admin-api.nblocks.cloud/flags/flag/FLAG_ID

Headers

Parameter Type Required Description
x-api-key string Required Your app api key

URL Parameters

Parameter Description
FLAG_ID The ID of the flag

Response

HTTP 200

Import data

Import data into your Nblocks app using these endpoints.

Import tenants

Request example:

[
   {
      "tenant":{
         "name":"John Ltd",
         "plan":"MEDIUM",
         "owner":{
            "username":"peter@doe.com",
            "firstName":"Peter",
            "lastName":"Doe"
         }
      },
      "users":[
         {
            "username":"john@doe.com",
            "firstName":"John",
            "lastName":"Doe",
            "role":"ADMIN"
         },
         {
            "username":"lisa@doe.com",
            "firstName":"Lisa",
            "lastName":"Doe",
            "role":"ADMIN",
            "password": { 
               "value": "$2a$10$f8zztJfuSgYc0Z8SGA3jb./KB5a2GY8lmwa9bgbRv/P0.1XNBhovy", 
               "algorithm": "BCRYPT",
               "pepper": {
                  "value": "foobar", 
                  "position": "END"
               }
            }
         }
      ]
   },
   {
      "tenant":{
         "name":"",
         "plan":"",
         "owner":{
            "username":"foo@bar.com",
            "firstName":"Peter",
            "lastName":"Doe"
         }
      },
      "users":[]
   }
]

Response example:

{
    "status": "SCHEDULED",
    "reference": "606b00a61679e20008d5654b",
    "import": {
        "tenants": 2,
        "users": 4,
        "passwords": false,
        "errors": [],
        "warnings": [],
        "approved": true
    }
}

This endpoint allows you to import tenants and their users. No notification emails wil be sent to the imported users. The import is asynchronous so it will be scheduled immediately and then completed once every tenant and user has been imported. A notification will be sent to your email when the import has completed. Before you make the request, you can validate your input and check for errors or warnings.

How will the imported users authenticate?
The import supports importing new users both with or without existing passwords.

New users imported without a password can authenticated using the configured SSO option. Then will be asked to reset their password should they try to login with username.

When importing passwords Nblocks will use the imported password to authenticate the user once. Thereafter a new password digest is generated this will be used in all future authentications.

HTTP Request

POST https://account-api.nebulr-core.com/import/tenants

Body Parameters

Parameter Type Required Description
tenant ImportTenant Required Import data for the tenant
users ImportUser[] Optional All other users than the owner that should be imported to this tenant

ImportTenant

Parameter Type Required Description
name string Optional Name of the tenant.
owner ImportUser Required The owner for this tenant. There must be one owner
plan string Optional The plan must be present in the configured App business model
logo string Optional A URI to a logo.
metadata Record Optional Store metadata for your own business logic that will be returned in every Tenant response. This data will never be outputted to the end user

ImportUser

Parameter Type Required Description
username string Required The username / email.
role string Optional Role of the user
firstName string Optional Users first name
lastName string Optional Users last name
password ImportPassword Optional Import an existing password

ImportPassword

Parameter Type Required Description
value string Required The password digest.
algorithm string Required The algorithm that is being used. Possible values: BCRYPT, ARGON2I, MD5, SHA1, SHA256 or SHA512.
pepper ImportPasswordPepper Optional If the password should be peppered prior to validation. Read more.

ImportPasswordPepper

Parameter Type Required Description
value string Required The pepper value.
position string Required If the pepper should be prepended or appended the password. Possible values: BEGIN or END.

Response

HTTP 200

Tenant model

Validate import tenants data

[
   {
      "tenant":{
         "name":"John Ltd",
         "plan":"MEDIUM",
         "owner":{
            "username":"peter@doe.com",
            "firstName":"Peter",
            "lastName":"Doe"
         }
      },
      "users":[
         {
            "username":"john@doe.com",
            "firstName":"John",
            "lastName":"Doe",
            "role":"ADMIN"
         },
         {
            "username":"lisa@doe.com",
            "firstName":"Lisa",
            "lastName":"Doe",
            "role":"ADMIN",
            "password": { 
               "value": "$2a$10$f8zztJfuSgYc0Z8SGA3jb./KB5a2GY8lmwa9bgbRv/P0.1XNBhovy", 
               "algorithm": "BCRYPT",
               "pepper": {
                  "value": "foobar", 
                  "position": "END"
               }
            }
         }
      ]
   },
   {
      "tenant":{
         "name":"",
         "plan":"",
         "owner":{
            "username":"foo@bar.com",
            "firstName":"Peter",
            "lastName":"Doe"
         }
      },
      "users":[]
   }
]

Response example:

{
    "tenants": 2,
    "users": 4,
    "passwords": false,
    "errors": [
        "One or more users are missing an username"
    ],
    "warnings": [],
    "approved": false
}

Validates the import body and returns a result that summarizes the import and if there are any errors or warnings.

HTTP Request

POST https://account-api.nebulr-core.com/import/validateTenants

Body Parameters

Parameter Type Required Description
tenant ImportTenant Required Import data for the tenant
users ImportUser[] Optional All other users than the owner that should be imported to this tenant

ImportTenant

Parameter Type Required Description
name string Optional Name of the tenant.
owner ImportUser Required The owner for this tenant. There must be one owner
plan string Optional The plan must be present in the configured App business model
logo string Optional A URI to a logo.
metadata Record Optional Store metadata for your own business logic that will be returned in every Tenant response. This data will never be outputted to the end user

ImportUser

Parameter Type Required Description
username string Required The username / email.
role string Optional Role of the user
firstName string Optional Users first name
lastName string Optional Users last name
password ImportPassword Optional Import an existing password

ImportPassword

Parameter Type Required Description
value string Required The password digest.
algorithm string Required The algorithm that is being used. Possible values: BCRYPT, ARGON2I, MD5, SHA1, SHA256 or SHA512.
pepper ImportPasswordPepper Optional If the password should be peppered prior to validation. Read more.

ImportPasswordPepper

Parameter Type Required Description
value string Required The pepper value.
position string Required If the pepper should be prepended or appended the password. Possible values: BEGIN or END.

Webhook

These events are sent to your webhook endpoint. See Update app profile how to configure a webhook

Tenant created event

Request example:

{
    "events": [
        {
            "type": "TENANT_CREATED",
            "timestamp": "2023-08-11T08:10:28.240Z",
            "data": {
                "id": "63cad6ac48dcba47e9322848",
                "mfa": false,
                "locale": "en",
                "name": "John's place",
                "logo": "",
                "metadata": {},
                "createdAt": "2023-01-20T18:00:12.393Z",
                "paymentsEnabled": false,
                "paymentsRequired": false,
                "onboarded": true
            }
        }
    ]
}
Parameter Type Description
type string Event type
timestamp string When the event occurred
data Tenant Event body

Tenant updated event

Request example:

{
    "events": [
        {
            "type": "TENANT_UPDATED",
            "timestamp": "2023-08-11T08:10:28.240Z",
            "data": {
                "id": "63cad6ac48dcba47e9322848",
                "mfa": false,
                "locale": "en",
                "name": "John's place",
                "logo": "",
                "metadata": {},
                "createdAt": "2023-01-20T18:00:12.393Z",
                "paymentsEnabled": false,
                "paymentsRequired": false,
                "onboarded": true
            }
        }
    ]
}
Parameter Type Description
type string Event type
timestamp string When the event occurred
data Tenant Event body

Tenant user created event

Request example:

{
    "events": [
        {
            "type": "TENANT_USER_CREATED",
            "timestamp": "2023-08-11T08:29:22.469Z",
            "data": {
                "id": "63cad6ac48dcba47e9322853",
                "role": "OWNER",
                "email": "john.doe@example.com",
                "username": "john.doe@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "fullName": "John Doe",
                "onboarded": true,
                "consentsToPrivacyPolicy": false,
                "enabled": true,
                "teams": [
                    "cool_gang"
                ],
                "createdAt": "2023-01-20T18:00:12.489Z",
                "tenant": {
                    "id": "63cad6ac48dcba47e9322848",
                    "mfa": false,
                    "locale": "en",
                    "name": "John's place",
                    "logo": "",
                    "metadata": {},
                    "createdAt": "2023-01-20T18:00:12.393Z",
                    "paymentsEnabled": false,
                    "paymentsRequired": false,
                    "onboarded": true
                }
            }
        }
    ]
}
Parameter Type Description
type string Event type
timestamp string When the event occurred
data Tenant user Event body

Tenant user updated event

Request example:

{
    "events": [
        {
            "type": "TENANT_USER_UPDATED",
            "timestamp": "2023-08-11T08:29:22.469Z",
            "data": {
                "id": "63cad6ac48dcba47e9322853",
                "role": "OWNER",
                "email": "john.doe@example.com",
                "username": "john.doe@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "fullName": "John Doe",
                "onboarded": true,
                "consentsToPrivacyPolicy": false,
                "enabled": true,
                "teams": [
                    "cool_gang"
                ],
                "createdAt": "2023-01-20T18:00:12.489Z",
                "tenant": {
                    "id": "63cad6ac48dcba47e9322848",
                    "mfa": false,
                    "locale": "en",
                    "name": "John's place",
                    "logo": "",
                    "metadata": {},
                    "createdAt": "2023-01-20T18:00:12.393Z",
                    "paymentsEnabled": false,
                    "paymentsRequired": false,
                    "onboarded": true
                }
            }
        }
    ]
}
Parameter Type Description
type string Event type
timestamp string When the event occurred
data Tenant user Event body

Tenant user deleted event

Request example:

{
    "events": [
        {
            "type": "TENANT_USER_DELETED",
            "timestamp": "2023-08-11T08:29:22.469Z",
            "data": {
                "id": "63cad6ac48dcba47e9322853",
                "role": "OWNER",
                "email": "john.doe@example.com",
                "username": "john.doe@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "fullName": "John Doe",
                "onboarded": true,
                "consentsToPrivacyPolicy": false,
                "enabled": true,
                "teams": [
                    "cool_gang"
                ],
                "createdAt": "2023-01-20T18:00:12.489Z",
                "tenant": {
                    "id": "63cad6ac48dcba47e9322848",
                    "mfa": false,
                    "locale": "en",
                    "name": "John's place",
                    "logo": "",
                    "metadata": {},
                    "createdAt": "2023-01-20T18:00:12.393Z",
                    "paymentsEnabled": false,
                    "paymentsRequired": false,
                    "onboarded": true
                }
            }
        }
    ]
}
Parameter Type Description
type string Event type
timestamp string When the event occurred
data Tenant user Event body

Models

App profile model

Model example:

{
    "id": "624c14cc0c01e70033356282",
    "name": "My app",
    "domain": "MY_APP",
    "apiUrl": "http://localhost:3000",
    "uiUrl": "http://localhost:8100",
    "webhookUrl": "http://api.example.com/webhook"
    "stripeEnabled": false,
    "passkeysEnabled": true,
    "azureMarketplaceEnabled": false,
    "googleSsoEnabled": false,
    "azureAdSsoEnabled": true,
    "onboardingFlow": "B2B",
    "cloudViews": true,
    "redirectUris": ["http://localhost:8080/auth/oauth-callback"],
    "defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
    "defaultRole": "OWNER",
    "roles": {
        "OWNER": [
            "AUTHENTICATED",
            "TENANT_READ",
            "TENANT_WRITE",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "TAG_WRITE",
            "USER_READ",
            "USER_WRITE",
            "GROUP_WRITE",
            "GROUP_READ",
            "ASSIGNEES_WRITE",
            "SETTINGS_READ",
            "SETTINGS_WRITE"
        ],
        "ADMIN": [
            "AUTHENTICATED",
            "TENANT_READ",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "TAG_WRITE",
            "USER_READ",
            "USER_WRITE",
            "GROUP_WRITE",
            "GROUP_READ",
            "ASSIGNEES_WRITE",
            "SETTINGS_READ",
            "SETTINGS_WRITE"
        ],
        "MANAGER": [
            "AUTHENTICATED",
            "TENANT_READ",
            "CASE_READ",
            "CASE_WRITE",
            "TAG_READ",
            "USER_READ",
            "GROUP_READ",
            "SETTINGS_READ"
        ],
    },
    "businessModel": {
        "taxes": [
            {
            "region": "SE",
            "name": "VAT",
            "percentage": 25
            }
        ],
        "plans": [
            {
            "name": "ESSENTIAL",
            "prices": [
                {
                "region": "SE",
                "amount": 500,
                "currency": "SEK",
                "recurrenceInterval": "month"
                },
                {
                "region": "DE",
                "amount": 50,
                "currency": "EUR",
                "recurrenceInterval": "month"
                }
            ]
            },
            {
            "name": "TEAM",
            "trialDays": 14,
            "prices": [
                {
                "region": "SE",
                "amount": 1000,
                "currency": "SEK",
                "recurrenceInterval": "month"
                },
                {
                "region": "DE",
                "amount": 100,
                "currency": "EUR",
                "recurrenceInterval": "month"
                }
            ]
            }
        ]
    },
    "logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
    "websiteUrl": "http://localhost",
    "privacyPolicyUrl": "",
    "termsOfServiceUrl": ""
}
Parameter Type Description
id string Unique ID (Read only)
name string Name of the app
domain string Unique domain name of the app (Read only)
apiUrl string URL to your api (to receive webhooks etc).
webhookUrl string Enable webhook and events to be sent to this url
defaultRole string Default user role
uiUrl string URL to your frontend app (for onboarding redirects etc).
roles Record All user roles and their granted privileges
businessModel BusinessModel The business model defines what plans are available to subscribe to and what taxes applies.
logo string URL to your logo
websiteUrl string URL to your website or landing page. E.g. Branded emails will link to this URL, checkout process will redirect to /payment-success and /payment-cancel
privacyPolicyUrl string URL to a page on your website containing a Privacy policy for your app users. E.g. checkout process will link to this url.
termsOfServiceUrl string URL to a page on your website containing a Terms of service for your app users. E.g. checkout process will link to this url.
emailSenderName string Emails sent from Nblocks will have this sender name
emailSenderEmail string Emails sent from Nblocks will have this sender email. You'll have to verify this email before
stripeEnabled boolean Boolean value telling the user if Stripe is enabled (Read only)
passkeysEnabled boolean Boolean value telling the user if Login with Passkeys is enabled
azureMarketplaceEnabled boolean Boolean value telling the user if Azure marketplace is enabled (Read only)
googleSsoEnabled boolean Boolean value telling the user if Login with Google SSO is enabled (Read only)
azureAdSsoEnabled boolean Boolean value telling the user if Login with Azure SSO is enabled (Read only)
onboardingFlow OnboardingFlow Configure how users will be onboarded
cloudViews boolean Toggle this to true if you want to use a UI provided by NBlocks instead of your own
redirectUris string[] Allowed redirect uris
defaultCallbackUri string Default handover/callback uri used by Nblocks

Business model

Model example:

{
        "taxes": [
            {
            "region": "SE",
            "name": "VAT",
            "percentage": 25
            }
        ],
        "plans": [
            {
            "name": "ESSENTIAL",
            "prices": [
                {
                "region": "SE",
                "amount": 500,
                "currency": "SEK",
                "recurrenceInterval": "month"
                },
                {
                "region": "DE",
                "amount": 50,
                "currency": "EUR",
                "recurrenceInterval": "month"
                }
            ]
            },
            {
            "name": "TEAM",
            "trialDays": 14,
            "prices": [
                {
                "region": "SE",
                "amount": 1000,
                "currency": "SEK",
                "recurrenceInterval": "month"
                },
                {
                "region": "DE",
                "amount": 100,
                "currency": "EUR",
                "recurrenceInterval": "month"
                }
            ]
            }
        ]
}
Parameter Type Description
taxes Tax[] A list of Taxes for different countries
plans Plan[] A list of Plans which your customers can subscribe to

Tenant model

{
    "id": "624c14cc0c01e70033356285",
    "plan": "TEAM",
    "mfa": false,
    "paymentsEnabled": false,
    "paymentsRequired": false,
    "locale": "en",
    "name": "Nebulr AB",
    "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
    "metadata": {},
    "onboarded": true,
    "createdAt": "2022-04-05T10:07:08.235Z"
}
Parameter Type Description
id string Unique ID (Read only)
plan string Name of the subscription plan. Automatically set by the payment service if tenant used the checkout process
locale string The default locale / lang code for all users in this tenant (ISO_639-1 format). This property will set the i18n for all platform emails
name string Name of the tenant
logo string URI to a logo
mfa boolean Require users to login with MFA/2FA
paymentsEnabled boolean The tenant has been setup with a payment solution
paymentsRequired boolean The tenant should setup payment immediately because tenant has not setup payments and the subscribing plan carry a cost or the trial has ended
metadata Record Custom key value meta data that you can use
onboarded string If this tenant is considered onboarded (Read only)
createdAt string Timestamp when created (Read only)

Tenant user model

{
    "id": "63cad6ac48dcba47e9322853",
    "role": "OWNER",
    "email": "john.doe@example.com",
    "username": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "onboarded": true,
    "consentsToPrivacyPolicy": false,
    "enabled": true,
    "teams": [
        "cool_gang"
    ],
    "createdAt": "2023-01-20T18:00:12.489Z",
    "tenant": {
        "id": "63cad6ac48dcba47e9322848",
        "mfa": false,
        "locale": "en",
        "name": "John's place",
        "logo": "",
        "metadata": {},
        "createdAt": "2023-01-20T18:00:12.393Z",
        "paymentsEnabled": false,
        "paymentsRequired": false,
        "onboarded": true
    }
}
Parameter Type Description
id string Unique ID (Read only)
role string Role of the user. Grants a set of privileges. Privileges are configured on the App model.
email string Email address
username string Username
firstName string Users first name
lastName string Users last name
fullName string Users full name (first name and last name concatenated)
onboarded boolean If user is onboarded or not
consentsToPrivacyPolicy boolean If user have left consent to the app privacy policy or not (should be set during app onboarding)
enabled boolean If user should be allowed to login or not
teams string[] Array of identifiers that can be used to group several users into teams or groups
createdAt string Timestamp when created (Read only)
tenant Tenant The tenant

Tokens response

Parameter Type Description
token_type string Token type
expires_in number Seconds before the access_token expires
access_token string (JWT) The access token containing authentication and access control data only)
refresh_token string (JWT) The token use for refreshing the access token before it expires app
id_token string (JWT) The OpenId Connect user profile id
user_profile object A decoded id_token JWT as JSON. Available in Shorthand get tokens endpoint

Access token model

{
  "sub": "63d25a9e0796d40008680f9a",
  "scope": "TENANT_WRITE TENANT_READ USER_WRITE USER_READ AUTHENTICATED",
  "role": "OWNER",
  "aid": "624c14cc0c01e70033356282",
  "tid": "63d25a9e0796d40008680f96",
  "plan": "Basic"
}

Decoded JWT payload.

Parameter Type Description
sub string User id
scope string User privileges
role string User role
aid string Your app id
tid string User tenant id
plan string User tenant plan

Id token model

{
  "sub": "63d25a9e0796d40008680f9a"
  "name": "John Doe",
  "family_name": "Doe",
  "given_name": "John",
  "preferred_username": "john@example.com",
  "locale": "en",
  "email": "john@example.com",
  "email_verified": true,
  "onboarded": true,
  "tenant_id": "63d25a9e0796d40008680f96",
  "tenant_name": "Johns Family",
  "tenant_locale": "en",
  "tenant_logo": "",
}

Decoded JWT payload.

Parameter Type Description
sub string User id
name string Users full name
family_name string Users last name
given_name string Users first name
preferred_username string Username
locale string Users preferred locale
email string User email
email_verified boolean The users email address has been verified
onboarded boolean Have the user completed onboarding or not
tenant_id string Tenant id
tenant_name string Tenant name
tenant_locale string The preferred locale of the whole tenant
tenant_logo string Tenant logo URI

Import tenant response

Model example:

{
    "status": "SCHEDULED",
    "import": {
        "tenants": 2,
        "users": 4,
        "passwords": false,
        "errors": [],
        "warnings": [],
        "approved": true
    }
}
Parameter Type Description
status string User context
import Validate response A summary of the import and if there are any errors

Validate import tenant response

Model example:

{
    "tenants": 2,
    "users": 4,
    "passwords": false,
    "errors": [
        "One or more users are missing an username"
    ],
    "warnings": [],
    "approved": false
}
Parameter Type Description
tenants number The total numbers of tenants that will be imported
users number The total numbers of users (across all tenants) that will be imported
passwords boolean If there will be any user credentials migrated during the import
errors string[] A list of errors. These errors are blocking the import
warnings string[] A list of warnings. These warnings are not blocking the import
approved boolean If the data will or was approved for import

Feature flags evaluation context

Model example:

{
    "user": {
        "key": "foobar",
        "id": "63d2ab029e23db0afb07a5a7",
        "role": "ADMIN",
        "name": "John Doe";
    }

    "org": {
        "key": "helloworld",
        "id": "63d2ab029e23db0afb07a5a7",
        "plan": "PREMIUM",
        "name": "My Workspace"
    }

    "device": {
        "key": "iphone"
    }
}
Parameter Type Description
user UserContext User context
org OrgContext Org context
device KeyContext Device context

UserContext

Parameter Type Description
key string Custom value
id string User id
role string User role
name string User name

OrgContext

Parameter Type Description
key string Custom value
id string Tenant id
plan string Tenant plan
name string Tenant name

KeyContext

Parameter Type Description
key string The value to be matched (==)

Feature flags segment

Model example:

{
    "id": "64c6400fdaf20f0008e71b25",
    "key": "admins",
    "description": "This segment targets admins",
    "targets": [
        {
            "user": {
                "role": {
                    "operator": "eq",
                    "value": "ADMIN"
                }
            }
        }
    ]
}
Parameter Type Description
id string Unique ID (Read only)
key string Segment key. Use this to reference the segment in a flag
description string Description text
targets Target[] The target which will be used to match

Feature flags segment target

Model example:

{
    "device": {
        "key": {
            "operator": "contains",
            "value": "iphone"
        }
    }
}
Parameter Type Description
user UserTarget User id
org OrgTarget Users full name
device KeyTarget Users last name

UserTarget

Parameter Type Description
key TargetValue Custom value
id string User id
role TargetValue User role
name TargetValue User name

OrgTarget

Parameter Type Description
key TargetValue Custom value
id string Tenant id
plan TargetValue Tenant plan
name TargetValue Tenant name

KeyTarget

Parameter Type Description
key TargetValue The value to be matched

TargetValue

Parameter Type Description
operator Operator The matching operator
value string The value to be matched using the operator

Operator

Operator Description
eq It should be equal to the value (==)
beginsWith It should begin with the value
endsWith It should end with the value
contains It should contain the value

Feature flags flag

Model example:

{
    "id": "64c64cfb47418500082f60b5",
    "key": "iphone-feature",
    "description": "A feature for iPhones",
    "defaultValue": false,
    "segments": [
        {
            "id": "64c63e7adaf20f0008e71b20",
            "key": "iphones",
            "description": "This segment targets iPhones",
            "targets": [
                {
                    "device": {
                        "key": "iphone"
                    }
                }
            ]
        }
    ],
    "targetValue": true,
    "enabled": true
}
Parameter Type Description
id string Unique ID (Read only)
key string Flag key. Use this to reference the flag when evaluating
description string Description text
defaultValue boolean The value to return if no segment was found or matched
segments List of Segment The segments and matchers that are linked to this flag
targetValue boolean The value to return of a segment was matched
enabled boolean Active state. Only enabled flags are available for evaluation. Otherwise evaluation falls back to false.

Errors

Nblocks uses the following errors to explain what went wrong. All APIs use this error schema.

Error Code Error message
NBLOCKS_CONFLICT You cannot have two users with the same email in the same tenant.
NBLOCKS_USER_NOT_FOUND User not found.
NBLOCKS_UNKNOWN_LOGIN_STRATEGY Unknown login strategy.
NBLOCKS_UNKNOWN_APP_ID App Id is missing.
NBLOCKS_APP_UNAUTHORIZED_EXCEPTION App is unauthenticated. This usually means your APP API Key is not valid.
NBLOCKS_UNAUTHORIZED_EXCEPTION User is unathenticated. Please login first.
INVALID_MFA_CODE_EXCEPTION The MFA code your provided is invalid or expired.
NBLOCKS_FORBIDDEN_EXCEPTION You do not have access to this resource.
NBLOCKS_FEATURE_FORBIDDEN_EXCEPTION You do not have access to this feature.
NBLOCKS_MISSING_CREDENTIALS Missing required variables to authorize.
NBLOCKS_MISSING_USERNAME Missing username.
NBLOCKS_MISSING_APP Missing app.
NBLOCKS_WRONG_CREDENTIALS Wrong user credentials.
NBLOCKS_INVALID_AUTH_TOKEN Invalid auth token.
NBLOCKS_INVALID_ROLE The role you're changing to are not within your defined app roles.
NBLOCKS_OWNER_ROLE_MUST_EXIST Your app must have the role OWNER.
NBLOCKS_NOT_FOUND_TENANT_EXCEPTION Tenant do not exists
NBLOCKS_MISSING_REQUIRED_VARIABLES_EXCEPTION You're missing some required variables or the ones you've provided are not formated correctly
NBLOCKS_INVALID_OAUTH_SCOPE_ERROR The scope requested are not allowed for this client
NBLOCKS_INVALID_REDIRECT_URI_ERROR Invalid redirect_uri
NBLOCKS_INVALID_GRANT_TYPE_ERROR Unsupported grant_type
NBLOCKS_INVALID_RESPONSE_TYPE_ERROR Unsupported response_type
NBLOCKS_STRIPE_OUT_OF_SYNC_EXCEPTION It seems that the the data in your stripe account don't match your business model. Update your business model to resync the integration
NBLOCKS_ERROR An error occured. Please try again

Changelog

September 2023

Nblocks Login * Passkeys support * Added signup flow

August 2023

Affected APIs:

July 2023

Affected APIs:

June 2023

Affected APIs:

May 2023

azureAdClientId

Affected APIs:

April 2023

Improving onboarding information

Adding the onboarded property to both tenantUser and tenant responses.

Affected APIs:

March 2023

Brandable email templates

Enable developers to change the default email templates from the communication api to accomplish a fully customized branding.

getEmailTemplate, overrideEmailTemplate, resetEmailTemplate.

Affected APIs:

February 2023

Launching Auth service, Backendless and Cloud views.

Auth service: Oauth 2.0 login, JWTs and callback/handover functionality. Cloud views: Login flow so that any tech stack can use Nblocks login. Backendless: Powers cloud views but also any Nblocks UI plugin.

Adding the cloudviews property to turn on/off this functionality to app profile.

Affected APIs:

October 2022

PDF generation

Affected APIs:

September 2022

Cloud hosted checkout view for simpler integration with Stripe

Affected APIs:

August 2022

File storage meta data cleansing support

Affected APIs:

May 2022

Launching voice call redirect api.

Now you can expose a phone number and configure a rule set how and to which recipients this call should be routed to.

Adding listVoiceRedirectRules, createVoiceRedirectRule, updateVoiceRedirectRule, deleteVoiceRedirectRule, listVoiceRedirectErrors.

Affected APIs:

February 2022

January 2022

December 2021

Soft launch