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.

Custom email templates for emails sent to your users via Nblock
Custom CSS for the Nblocks hosted views that you embedd in your application
Custom translations for the Nblocks hosted views that you embedd in your application

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:

You initiate the login process by redirecting the user to the /authorize endpoint (or the simpler shorthand /login and /signup endpoints).
User is pulled through an authentication process provided by Nblocks with cloud views.
Once the user is authenticated and has selected the tenant to access the user is redirect back to your app with a code.
You make a call to the /token endpoint with this code to exchange it for access tokens and user profile information (openid).
You can verify that the tokens are valid and safe to trust by using the public keys available from the /.well-known endpoint.
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`

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:

Restrict access to premium content that just users with a certain plan can access
Try beta features on a selection of customers
Show a message to all users during a scheduled release.

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.

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

Launch of Feature flags.

Affected APIs:

https://backendless.nblocks.cloud
https://admin-api.nblocks.cloud

July 2023

Brandning of User management portal with CSS and translations

Affected APIs:

https://backendless.nblocks.cloud

June 2023

Support for embedding User management portal
Google SSO

Affected APIs:

https://backendless.nblocks.cloud
https://auth.nblocks.cloud

May 2023

Introduction of Azure AD SSO and Azure Marketplace integration.
Trial support for your plans

azureAdClientId

Affected APIs:

https://auth.nblocks.cloud
https://account-api.nebulr-core.com

April 2023

Improving onboarding information

Adding the onboarded property to both tenantUser and tenant responses.

Affected APIs:

https://auth.nblocks.cloud
https://account-api.nebulr-core.com

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:

https://communication-api.nebulr-core.com

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:

https://auth.nblocks.cloud
https://account-api.nebulr-core.com

October 2022

PDF generation

Affected APIs:

https://file-api.nebulr-core.com

September 2022

Cloud hosted checkout view for simpler integration with Stripe

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

Affected APIs:

August 2022

File storage meta data cleansing support

Affected APIs:

https://file-api.nebulr-core.com

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

MFA support

January 2022

Custom email sender
Default role for new users

December 2021

Soft launch

Start

Authentication

How it works

Registrating for a new app profile

App Profile

Get app profile

HTTP Request

Headers

Response

Update app profile

HTTP Request

Body Parameters

Response

Update credentials

HTTP Request

Body Parameters

Response

Branding

Set custom email template

HTTP Request

Headers

URL Parameters

Body Parameters

Response

Get custom email template

HTTP Request

Headers

URL Parameters

Response

Delete custom email template

HTTP Request

Headers

URL Parameters

Response

Set custom CSS

HTTP Request

Headers

Body Parameters

Response

Get your custom CSS

HTTP Request

Headers

Response

Set custom Translations

HTTP Request

Headers

Body Parameters

Response

Get your custom Translations

HTTP Request

Headers

Response

User authentication

Authorize

HTTP Request

Query Parameters

Get tokens

HTTP Request

Body Parameters

Response

Short hand authorize

HTTP Request

URL Parameters

Query Parameters

Short hand signup

HTTP Request

URL Parameters

Query Parameters

Shorthand get tokens

HTTP Request

URL Parameters

Body Parameters

Response

Handover code

HTTP Request

URL Parameters

Body Parameters

Response

Users

User management portal - Users