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 Nblocks app

Creating via Nblocks Admin

Go to Nblocks Admin and signup for a new account if you don't already have one.

Once you have logged in to your account you will be able to create new apps. Use the API key and the App ID to start calling our APIs.

Creating via terminal

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 and its profile is your entrypoint to Nblocks. This is your unique set of settings to tailor the Nblocks experience. You can have several different apps, 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",
    "emailSenderName": "My App",
    "emailSenderEmail": "noreply@myapp.com",
    "webhookUrl": "http://api.example.com/webhook"
    "stripeEnabled": false,
    "paymentsAutoRedirect": true,
    "passkeysEnabled": true,
    "magicLinkEnabled": true,
    "mfaEnabled": true,
    "azureMarketplaceEnabled": false,
    "googleSsoEnabled": false,
    "azureAdSsoEnabled": true,
    "linkedinSsoEnabled": true,
    "githubSsoEnabled": true,
    "facebookSsoEnabled": true,
    "onboardingFlow": "B2B",
    "tenantSelfSignup": true,
    "cloudViews": true,
    "redirectUris": ["http://localhost:8080/auth/oauth-callback"],
    "defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
    "logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
    "websiteUrl": "http://localhost",
    "privacyPolicyUrl": "",
    "termsOfServiceUrl": "",
    "accessTokenTTL": 3600,
    "refreshTokenTTL": 604800
}

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",
    "emailSenderName": "My App",
    "emailSenderEmail": "noreply@myapp.com",
    "webhookUrl": "http://api.example.com/webhook"
    "stripeEnabled": false,
    "paymentsAutoRedirect": true,
    "passkeysEnabled": true,
    "magicLinkEnabled": true,
    "mfaEnabled": true,
    "azureMarketplaceEnabled": false,
    "googleSsoEnabled": false,
    "azureAdSsoEnabled": true,
    "linkedinSsoEnabled": true,
    "githubSsoEnabled": true,
    "facebookSsoEnabled": true,
    "onboardingFlow": "B2B",
    "tenantSelfSignup": true,
    "cloudViews": true,
    "redirectUris": ["http://localhost:8080/auth/oauth-callback"],
    "defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
    "logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
    "websiteUrl": "http://localhost",
    "privacyPolicyUrl": "",
    "termsOfServiceUrl": "",
    "accessTokenTTL": 3600,
    "refreshTokenTTL": 604800
}

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).
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
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
tenantSelfSignup	boolean	Optional	Toggle this to true if you want to allow users to signup for new workspaces themselves
redirectUris	string[]	Optional	Allowed redirect uris
defaultCallbackUri	string	Optional	Default handover/callback uri used by Nblocks
stripeEnabled	boolean	Optional	Toggle this to true if you want to allow payments through Stripe for your users
paymentsAutoRedirect	boolean	Optional	Activates redirect to select payments plans and takes a user to selection of payment plans directly after signup or after a trial has ended.
passkeysEnabled	boolean	Optional	Toggle this to true if you want to allow your users to login with passkeys
magicLinkEnabled	boolean	Optional	Toggle this to true if you want to allow your users to login with Magic-Link
mfaEnabled	boolean	Optional	Toggle this to true if you want to allow your tenants to use multi-factor authentication
azureMarketplaceEnabled	boolean	Optional	Toggle this to true if you want to allow your users to register through Azure marketplace
googleSsoEnabled	boolean	Optional	Toggle this to true if you want to allow your users to login using Google SSO
linkedinSsoEnabled	boolean	Optional	Toggle this to true if you want to allow your users to login using LinkedIn SSO
githubSsoEnabled	boolean	Optional	Toggle this to true if you want to allow your users to login using Github SSO
facebookSsoEnabled	boolean	Optional	Toggle this to true if you want to allow your users to login using Facebook SSO
azureAdSsoEnabled	boolean	Optional	Toggle this to true if you want to allow your users to login using Azure SSO
accessTokenTTL	number	Optional	Configure the access token lifetime in seconds
refreshTokenTTL	number	Optional	Configure the refresh token lifetime in seconds

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"
}'

Response example:

{
    "stripeCredentialsAdded": true,
    "azureMarketplaceCredentialsAdded": true,
    "azureAdSsoCredentialsAdded": false,
    "googleSsoCredentialsAdded": true
}

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 and social login providers like Google and Microsoft Azure AD.

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
microsoftAzureADClientId	string	Optional	MS Azure AD SSO
microsoftAzureADClientSecret	string	Optional	MS Azure AD SSO
microsoftAzureADTenantId	string	Optional	MS Azure AD SSO

Response

HTTP 200

Your Credentials state model

Get credentials state

Request example

const credentialsState = await client.config.getCredentialsState();

curl --request GET 'https://account-api.nebulr-core.com/app/credentialsState' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "stripeCredentialsAdded": true,
    "azureMarketplaceCredentialsAdded": true,
    "azureAdSsoCredentialsAdded": false,
    "googleSsoCredentialsAdded": true
}

Although the credentials are never displayed again, you can always get their states to confirm they've been added.

HTTP Request

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

Headers

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

Response

HTTP 200

Your Credentials state model

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/email/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/email/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/email/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/email/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/email/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/email/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

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

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://admin-api.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 201

Get your custom CSS

Request example

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

Response example:

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

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

HTTP Request

GET https://admin-api.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

Delete your custom CSS

Request example

curl --request DELETE 'https://admin-api.nblocks.cloud/brand/css' \
--header 'x-api-key: YOUR_APP_API_KEY'

Deleting a custom CSS file will restore Nblocks to the default styling.

HTTP Request

DELETE https://admin-api.nblocks.cloud/brand/css

Headers

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

Response

HTTP 200

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
responseType	`'code'` or `'id_token'`	Optional	If the response should be a code that could be exchanged for tokens or just an Id token
signup	boolean	Optional	If you want to initiate a signup instead of the default login flow for the user.
signup_plan	string	Optional	The key to an existing plan. Allows the signup end with the new tenant subscribing to a specific plan.
signup_currency	string	Optional	A currency that matches one of the price in the plan.
signup_recurrence_interval	string	Optional	An interval that matches one of the price in the plan.
force_federation	`'ms-azure-ad'` or `'google'` or `'saml'`	Optional	If you want to force a certain federated login flow instead of letting the user choose during login. Saml flows requires federationConnection to be provided.
federation_connection	string	Optional	Specify what federation connection id to use when running `forceFederation`

Get tokens

Request example exchanging code for tokens

const response = await client.auth.getTokensAndVerify({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.refreshTokensAndVerify({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
responseType	`'code'` or `'id_token'`	Optional	If the response should be a code that could be exchanged for tokens or just an Id token
forceFederation	`'ms-azure-ad'` or `'google'` or `'saml'`	Optional	If you want to force a certain federated login flow instead of letting the user choose during login. Saml flows requires federationConnection to be provided.
federationConnection	string	Optional	Specify what federation connection id to use when running `forceFederation`

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
responseType	`'code'` or `'id_token'`	Optional	If the response should be a code that could be exchanged for tokens or just an Id token
signupPlan	string	Optional	The key to an existing plan. Allows the signup end with the new tenant subscribing to a specific plan.
signupCurrency	string	Optional	A currency that matches one of the price in the plan.
signupRecurrenceInterval	string	Optional	An interval that matches one of the price in the plan.
forceFederation	`'ms-azure-ad'` or `'google'` or `'saml'`	Optional	If you want to force a certain federated signup flow instead of letting the user choose during login. Saml flows requires federationConnection to be provided.
federationConnection	string	Optional	Specify what federation connection id to use when running `forceFederation`

Shorthand get tokens

Request example exchanging code for tokens

const response = await client.auth.getTokensAndVerify({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.refreshTokensAndVerify({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

Access

Access roles and privileges enable you to manage and specify the level of access that different users have within your application.

To effectively control user access, you must first create a set of Privileges and associate them with a Role. Afterward, you can assign these roles to individual Tenant users and ensure that their privileges are evaluated for various actions and resources within the application.

Some use cases for roles and privileges include:

Granting admin roles for full control over the system
Limiting guest users to read-only access
Assigning user-specific access to sensitive data

List roles

Request example

const roles = await client.config.access.roles.list();

curl --request GET 'https://account-api.nebulr-core.com/role' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "650cd8510ccba777cc9623de",
        "name": "OWNER",
        "key": "OWNER",
        "privileges": [
            {
                "id": "650cd8510ccba777cc9623d4",
                "key": "AUTHENTICATED",
                "description": "Privilege for all authenticated users"
            },
            {
                "id": "650cd8510ccba777cc9623d5",
                "key": "USER_READ"
            },
            {
                "id": "650cd8510ccba777cc9623d6",
                "key": "USER_WRITE"
            },
            {
                "id": "650cd8510ccba777cc9623d7",
                "key": "TENANT_READ"
            },
            {
                "id": "650cd8510ccba777cc9623d8",
                "key": "TENANT_WRITE"
            }
        ],
        "isDefault": false
    },
    {
        "id": "650ce65de49d5da5d31fa1c9",
        "name": "Super admin",
        "key": "SUPER_ADMIN",
        "description": "Super admin with user management privileges",
        "privileges": [
            {
                "id": "650cd8510ccba777cc9623d4",
                "key": "AUTHENTICATED",
                "description": "Privilege for all authenticated users"
            },
            {
                "id": "650cd8510ccba777cc9623d5",
                "key": "USER_READ"
            },
            {
                "id": "650cd8510ccba777cc9623d6",
                "key": "USER_WRITE"
            }
        ],
        "isDefault": true
    }
]

List all roles

HTTP Request

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

Headers

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

Response

HTTP 200

List of Roles

Create a role

Request example

const data = {
    name: "Admin",
    key: "ADMIN",
    description: "Admin with user read privileges",
    privileges: [
        "650cd8510ccba777cc9623d4",
        "650cd8510ccba777cc9623d5"
    ],
    isDefault: false
};
const createdRole = await client.config.access.roles.create(data);

curl --request POST 'https://account-api.nebulr-core.com/role' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "name": "Admin",
    "key": "ADMIN",
    "description": "Admin with user read privileges",
    "privileges": [
        "650cd8510ccba777cc9623d4",
        "650cd8510ccba777cc9623d5"
    ],
    "isDefault": false
}'

Response example:

{
    "id": "6516a9bd492d28b55cca8d6f",
    "name": "Admin",
    "key": "ADMIN",
    "description": "Admin with user read privileges",
    "privileges": [
        {
            "id": "650cd8510ccba777cc9623d4",
            "key": "AUTHENTICATED",
            "description": "Privilege for all authenticated users"
        },
        {
            "id": "650cd8510ccba777cc9623d5",
            "key": "USER_READ"
        }
    ],
    "isDefault": false
}

Create a role

HTTP Request

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

Headers

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

Body Parameters

Parameter	Type	Required	Description
name	string	Yes	A presentable label for this role
key	string	Yes	A unique key for this role
description	string	No	Optional description
privileges	Privilege IDs[]	Yes	A list of privilege IDs. The list cannot be empty
isDefault	boolean	No	Default value is `false`. If set to `true`, the existing default role will be set to `false`

Response

HTTP 200

Role

Update a role

Request example

const id = "6516a9bd492d28b55cca8d6f";
const data = {
    description: "Updated description for the admin role",
};
const updatedRole = await client.config.access.role(id).update(data);

curl --request PUT 'https://account-api.nebulr-core.com/role/6516a9bd492d28b55cca8d6f' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "description": "Updated description for the admin role"
}'

Response example:

{
    "id": "6516a9bd492d28b55cca8d6f",
    "name": "Admin",
    "key": "ADMIN",
    "description": "Updated description for the admin role",
    "privileges": [
        {
            "id": "650cd8510ccba777cc9623d4",
            "key": "AUTHENTICATED",
            "description": "Privilege for all authenticated users"
        },
        {
            "id": "650cd8510ccba777cc9623d5",
            "key": "USER_READ"
        }
    ],
    "isDefault": false
}

Update an existing role

HTTP Request

PUT https://account-api.nebulr-core.com/role/ROLE_ID

Headers

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

URL Parameters

Parameter	Description
ROLE_ID	The ID of the role

Body Parameters

Parameter	Type	Required	Description
name	string	No	A presentable label for this role
key	string	No	A unique key for this role. The `OWNER` key cannot be changed
description	string	No	Optional description
privileges	Privilege IDs[]	No	A list of privilege IDs. The list cannot be empty
isDefault	boolean	No	Changing to `false` from `true` is not possible. If set to `true` from `false`, the existing default role will be set to `false`

Response

HTTP 200

Role

Delete a role

Request example

const id = "6516a9bd492d28b55cca8d6f";
await client.config.access.role(id).delete();

curl --request DELETE 'https://account-api.nebulr-core.com/role/6516a9bd492d28b55cca8d6f' \
--header 'x-api-key: YOUR_APP_API_KEY'

Delete an existing role. Deleting a role will not remove related privileges. Default roles and the OWNER role cannot be deleted.

HTTP Request

DELETE https://account-api.nebulr-core.com/role/ROLE_ID

Headers

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

URL Parameters

Parameter	Description
ROLE_ID	The ID of the role

Response

HTTP 200

List privileges

Request example

const privileges = await client.config.access.privileges.list();

curl --request GET 'https://account-api.nebulr-core.com/role/privilege' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "650cd8510ccba777cc9623d4",
        "key": "AUTHENTICATED",
        "description": "Privilege for all authenticated users"
    },
    {
        "id": "650cd8510ccba777cc9623d5",
        "key": "USER_READ"
    },
    {
        "id": "650cd8510ccba777cc9623d6",
        "key": "USER_WRITE"
    },
    {
        "id": "650cd8510ccba777cc9623d7",
        "key": "TENANT_READ"
    },
    {
        "id": "650cd8510ccba777cc9623d8",
        "key": "TENANT_WRITE"
    }
]

List all privileges

HTTP Request

GET https://account-api.nebulr-core.com/role/privilege

Headers

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

Response

HTTP 200

List of Privileges

Create a privilege

Request example

const data = {
    key: "SENSITIVE_DATA",
    description: "Access to sensitive data",
};
const createdPrivilege = await client.config.access.privileges.create(data);

curl --request POST 'https://account-api.nebulr-core.com/role/privilege' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "key": "SENSITIVE_DATA",
    "description": "Access to sensitive data"
}'

Response example:

{
    "id": "6516b9cb492d28b55cca8daf",
    "key": "SENSITIVE_DATA",
    "description": "Access to sensitive data"
}

Create a privilege

HTTP Request

POST https://account-api.nebulr-core.com/role/privilege

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 privilege
description	string	No	Optional description

Response

HTTP 200

Privileges

Update a privilege

Request example

const id = "6516b9cb492d28b55cca8daf";
const data = {
    description: "Updated description for the sensitive data privilege",
};
const updatedPrivilege = await client.config.access.privilege(id).update(data);

curl --request PUT 'https://account-api.nebulr-core.com/role/privilege/6516b9cb492d28b55cca8daf' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "description": "Updated description for the sensitive data privilege"
}'

Response example:

{
    "id": "6516b9cb492d28b55cca8daf",
    "key": "SENSITIVE_DATA",
    "description": "Updated description for the sensitive data privilege"
}

Update an existing privilege

HTTP Request

PUT https://account-api.nebulr-core.com/role/privilege/PRIVILEGE_ID

Headers

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

URL Parameters

Parameter	Description
PRIVILEGE_ID	The ID of the privilege

Body Parameters

Parameter	Type	Required	Description
key	string	No	A unique key for this privilege.
description	string	No	Optional description

Response

HTTP 200

Privileges

Delete a privilege

Request example

const id = "6516b9cb492d28b55cca8daf";
await client.config.access.privilege(id).delete()

curl --request DELETE 'https://account-api.nebulr-core.com/role/privilege/6516b9cb492d28b55cca8daf' \
--header 'x-api-key: YOUR_APP_API_KEY'

Delete an existing privilege.

HTTP Request

DELETE https://account-api.nebulr-core.com/role/privilege/PRIVILEGE_ID

Headers

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

URL Parameters

Parameter	Description
PRIVILEGE_ID	The ID of the privilege

Response

HTTP 200

Federation connections

Federation connections are part of Enterprise login. They represent a way to authenticate with a remote Identity provider (IdP) using either SAML or OIDC. You can setup different types of connections and assign them to invidual or a group of tenants. The tenants will then use this method to login. Users of tenants with enterprise login will only be able to login this way. That's because the IdP now manage the application access.

List all connections

Request example

const response = await client.federation.list();

curl --request GET 'https://account-api.nebulr-core.com/federation/connection' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "6571edf9dc018000227ac448",
        "type": "saml",
        "name": "ACME SAML",
        "clientId": "client_1234",
        "loginUrl": "https://mocksaml.com/api/saml/sso",
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END CERTIFICATE-----",
        "requestMethod": "GET",
        "signedRequest": false,
        "signedRequestAlgorithm": "sha256",
        "createdAt": "2023-12-07T16:08:25.061Z"
    },
    {
        "id": "6571edf9dc018000227ac449",
        "type": "saml",
        "name": "Foobar SAML",
        "clientId": "client_1234",
        "loginUrl": "https://anotherIdP.com/api/saml/sso",
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END CERTIFICATE-----",
        "requestMethod": "POST",
        "signedRequest": true,
        "signedRequestAlgorithm": "sha256",
        "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END PRIVATE KEY-----",
        "createdAt": "2023-12-07T16:08:25.061Z"
    }
]

Lists all federation connections in your app. These can be assigned to tenants to enable them to authenticate.

HTTP Request

GET https://account-api.nebulr-core.com/federation/connection

Headers

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

Response

HTTP 200

A list of Federation connections

Get connection by id

Request example

const response = await client.federation.get('606b00a61679e20008a5654d');

curl --request GET 'https://account-api.nebulr-core.com/federation/connection/606b00a61679e20008a5654d' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "6571edf9dc018000227ac449",
        "type": "saml",
        "name": "Foobar SAML",
        "clientId": "client_1234",
        "loginUrl": "https://anotherIdP.com/api/saml/sso",
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END CERTIFICATE-----",
        "requestMethod": "POST",
        "signedRequest": true,
        "signedRequestAlgorithm": "sha256",
        "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END PRIVATE KEY-----",
        "createdAt": "2023-12-07T16:08:25.061Z"
    }
]

Get a single federation connection in your app

HTTP Request

GET https://account-api.nebulr-core.com/federation/connection/:CONNECTION_ID

Headers

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

URL Parameters

Parameter	Description
CONNECTION_ID	The ID of the connection

Response

HTTP 200

Federation connection

Create new connection

Request example

const response = await client.federation.create(
    {
        type: "saml",
        name: "My connection",
        clientId: "client_1234",
        loginUrl: "https://mocksaml.com/api/saml/sso",
        certificate: "MIIC4jCCAcoCCQC33wnybT5QZDKYRFfomGwz0TZ4Iw1ZN99Mm0eo2USlSRTVl7QHRTuiuSThHpLKQQ==",
        requestMethod: "GET",
        signedRequest: false
    });

curl --request POST 'https://account-api.nebulr-core.com/federation/connection' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "type": "saml",
        "name": "My connection",
        "clientId": "client_1234",
        "loginUrl": "https://mocksaml.com/api/saml/sso",
        "certificate": "MIIC4jCCAcoCCQC33wnybT5QZDKYRFfomGwz0TZ4Iw1ZN99Mm0eo2USlSRTVl7QHRTuiuSThHpLKQQ==",
        "requestMethod": "GET",
        "signedRequest": false
    }'

Response example:

[
    {
        "id": "6571edf9dc018000227ac449",
        "type": "saml",
        "name": "Foobar SAML",
        "clientId": "client_1234",
        "loginUrl": "https://anotherIdP.com/api/saml/sso",
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END CERTIFICATE-----",
        "requestMethod": "POST",
        "signedRequest": true,
        "signedRequestAlgorithm": "sha256",
        "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END PRIVATE KEY-----",
        "createdAt": "2023-12-07T16:08:25.061Z"
    }
]

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

HTTP Request

POST https://account-api.nebulr-core.com/federation/connection

Headers

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

Body Parameters

Parameter	Type	Required	Description
name	string	Required	A connection name. This will also be visible for users when logging in
clientId	string	Optional	The identifier assigned to your application by the IdP. This is sometimes not required
loginUrl	string	Required	The URL where the IdP expects to receive SAML authentication requests
certificate	string	Required	The public key certificate provided by the IdP to validate the SAML responses.
requestMethod	string	Optional	The preferred method for sending SAML requests, either HTTP GET Redirect (most common) or HTTP POST
signedRequest	boolean	Optional	Whether the IdP requires the SAML request to be signed or not.
signedRequestAlgorithm	`sha256` or `sha512`	Required if signedRequest	Request signing algorithm.
privateKey	string	Required if signedRequest	Request signing private key. The public key should be handover to IdP

Response

HTTP 201

Federation connection

Update connection

Request example

const response = await client.federation.update('606b00a61679e20008a5654d',
    {
        requestMethod: "POST"
    });

curl --request PUT 'https://account-api.nebulr-core.com/federation/connection/606b00a61679e20008a5654d' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "requestMethod": "POST"
    }'

Response example:

[
    {
        "id": "6571edf9dc018000227ac449",
        "type": "saml",
        "name": "Foobar SAML",
        "clientId": "client_1234",
        "loginUrl": "https://anotherIdP.com/api/saml/sso",
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END CERTIFICATE-----",
        "requestMethod": "POST",
        "signedRequest": true,
        "signedRequestAlgorithm": "sha256",
        "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END PRIVATE KEY-----",
        "createdAt": "2023-12-07T16:08:25.061Z"
    }
]

Update an existing connection.

HTTP Request

PUT https://account-api.nebulr-core.com/federation/connection/CONNECTION_ID

Headers

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

URL Parameters

Parameter	Description
CONNECTION_ID	The ID of the connection

Body Parameters

Parameter	Type	Required	Description
name	string	Optional	A connection name. This will also be visible for users when logging in
clientId	string	Optional	The identifier assigned to your application by the IdP. This is sometimes not required
loginUrl	string	Optional	The URL where the IdP expects to receive SAML authentication requests
certificate	string	Optional	The public key certificate provided by the IdP to validate the SAML responses.
requestMethod	string	Optional	The preferred method for sending SAML requests, either HTTP GET Redirect (most common) or HTTP POST
signedRequest	boolean	Optional	Whether the IdP requires the SAML request to be signed or not.
signedRequestAlgorithm	`sha256` or `sha512`	Optional	Request signing algorithm.
privateKey	string	Optional	Request signing private key. The public key should be handover to IdP

Response

HTTP 200

Federation connection

Delete a connection

Request example

await client.config.federation.delete("606b00a61679e20008a5654d");

curl --request DELETE 'https://account-api.nebulr-core.com/federation/connection/606b00a61679e20008a5654d' \
--header 'x-api-key: YOUR_APP_API_KEY'

Delete an existing connection.

HTTP Request

DELETE https://account-api.nebulr-core.com/federation/connection/CONNECTION_ID

Headers

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

URL Parameters

Parameter	Description
CONNECTION_ID	The ID of the connection

Response

HTTP 200

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.

List users by tenant

Request example

const users = await client.tenant('624c14cc0c01e70033356285').users.list();

curl --request GET 'https://account-api.nebulr-core.com/tenant/user' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'x-tenant-id: 624c14cc0c01e70033356285'

Response example:

[
    {
        "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"
        ],
        "lastSeen": "2023-01-20T18:00:12.489Z",
        "createdAt": "2023-01-20T18:00:12.489Z",
        "tenant": {
            "id": "624c14cc0c01e70033356285",
            "plan": "TEAM",
            "trial": false,
            "paymentStatus": {
                "shouldSelectPlan": false,
                "shouldSetupPayments": false,
                "provider": "STRIPE",
                "paymentsEnabled": true
            },
            "mfa": false,
            "locale": "en",
            "name": "Nebulr AB",
            "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
            "metadata": {},
            "onboarded": true,
            "signupBy": { 
                "email": "john@example.com", 
                "firstName": "John", 
                "lastName": "Doe" 
            },
            "createdAt": "2022-04-05T10:07:08.235Z"
        }
    }
]

List all users associated with a tenant.

HTTP Request

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

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your app api key
x-tenant-id	string	Required	The tenant id

Response

HTTP 200

A list of Tenant users

Get user by id

Request example

const user = await client.tenant('624c14cc0c01e70033356285').user('63cad6ac48dcba47e9322853').get();

curl --request GET 'https://account-api.nebulr-core.com/tenant/user/63cad6ac48dcba47e9322853' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'x-tenant-id: 624c14cc0c01e70033356285'

Response example:

{
    "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"
    ],
    "lastSeen": "2023-01-20T18:00:12.489Z",
    "createdAt": "2023-01-20T18:00:12.489Z",
    "tenant": {
        "id": "624c14cc0c01e70033356285",
        "plan": "TEAM",
        "trial": false,
        "paymentStatus": {
            "shouldSelectPlan": false,
            "shouldSetupPayments": false,
            "provider": "STRIPE",
            "paymentsEnabled": true
        },
        "mfa": false,
        "locale": "en",
        "name": "Nebulr AB",
        "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
        "metadata": {},
        "onboarded": true,
        "signupBy": { 
            "email": "john@example.com", 
            "firstName": "John", 
            "lastName": "Doe" 
        },
        "createdAt": "2022-04-05T10:07:08.235Z"
    }
}

Get a specific user in a tenant.

HTTP Request

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

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your app api key
x-tenant-id	string	Required	The tenant id

URL Parameters

Parameter	Description
USER_ID	The ID of the user

Response

HTTP 200

A Tenant user

List tenants by user

const users = await client.tenant('624c14cc0c01e70033356285').user('63cad6ac48dcba47e9322853').listAssociations();

curl --request GET 'https://account-api.nebulr-core.com/tenant/user/63cad6ac48dcba47e9322853/associations' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'x-tenant-id: 624c14cc0c01e70033356285'

Response example:

[
    {
        "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"
        ],
        "lastSeen": "2023-01-20T18:00:12.489Z",
        "createdAt": "2023-01-20T18:00:12.489Z",
        "tenant": {
            "id": "624c14cc0c01e70033356285",
            "plan": "TEAM",
            "trial": false,
            "paymentStatus": {
                "shouldSelectPlan": false,
                "shouldSetupPayments": false,
                "provider": "STRIPE",
                "paymentsEnabled": true
            },
            "mfa": false,
            "locale": "en",
            "name": "Nebulr AB",
            "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
            "metadata": {},
            "onboarded": true,
            "signupBy": { 
                "email": "john@example.com", 
                "firstName": "John", 
                "lastName": "Doe" 
            },
            "createdAt": "2022-04-05T10:07:08.235Z"
        }
    }
]

Lists all tenants a user is asssociated with

HTTP Request

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

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your app api key
x-tenant-id	string	Required	The tenant id

URL Parameters

Parameter	Description
USER_ID	The ID of the user

Response

HTTP 200

A list of Tenant users

Create user

Request example

const user = await client.tenant('624c14cc0c01e70033356285').users.create(
    {
        username: "john.doe@example.com",
        role: "OWNER",
        firstName: "John",
        lastName: "Doe"
    });

curl --request POST 'https://account-api.nebulr-core.com/tenant/user' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'x-tenant-id: 624c14cc0c01e70033356285'
--data-raw '{"username":"john.doe@example.com","role":"OWNER","firstName":"John","lastName":"Doe"}'

Response example:

{
    "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"
    ],
    "lastSeen": "2023-01-20T18:00:12.489Z",
    "createdAt": "2023-01-20T18:00:12.489Z",
    "tenant": {
        "id": "624c14cc0c01e70033356285",
        "plan": "TEAM",
        "trial": false,
        "paymentStatus": {
            "shouldSelectPlan": false,
            "shouldSetupPayments": false,
            "provider": "STRIPE",
            "paymentsEnabled": true
        },
        "mfa": false,
        "locale": "en",
        "name": "Nebulr AB",
        "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
        "metadata": {},
        "onboarded": true,
        "signupBy": { 
            "email": "john@example.com", 
            "firstName": "John", 
            "lastName": "Doe" 
        },
        "createdAt": "2022-04-05T10:07:08.235Z"
    }
}

Adds a user to to the given tenant. If the username doesn't exist, a new user will be created before being added.

HTTP Request

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

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your app api key
x-tenant-id	string	Required	The tenant id

Body Parameters

Parameter	Type	Required	Description
username	string	Required	Email address to the new user
role	string	Optional	The key for an existing Role
firstName	string	Optional	User's first name
lastName	string	Optional	User's last name
muteNotifications	boolean	Optional	Set this variable to true if you don't wish to send out any notifications to the user

Response

HTTP 201

A Tenant user

Update user

Request example

const user = await client.tenant('624c14cc0c01e70033356285').user('63cad6ac48dcba47e9322853').update(
    {
        role: "ADMIN",
        enabled: false,
    });

curl --request PUT 'https://account-api.nebulr-core.com/tenant/user/63cad6ac48dcba47e9322853' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'x-tenant-id: 624c14cc0c01e70033356285'
--data-raw '{"role":"ADMIN","enabled": false}'

Response example:

{
    "id": "63cad6ac48dcba47e9322853",
    "role": "ADMIN",
    "email": "jane.doe@example.com",
    "username": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "onboarded": true,
    "consentsToPrivacyPolicy": false,
    "enabled": false,
    "teams": [
        "cool_gang"
    ],
    "lastSeen": "2023-01-20T18:00:12.489Z",
    "createdAt": "2023-01-20T18:00:12.489Z",
    "tenant": {
        "id": "624c14cc0c01e70033356285",
        "plan": "TEAM",
        "trial": false,
        "paymentStatus": {
            "shouldSelectPlan": false,
            "shouldSetupPayments": false,
            "provider": "STRIPE",
            "paymentsEnabled": true
        },
        "mfa": false,
        "locale": "en",
        "name": "Nebulr AB",
        "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
        "metadata": {},
        "onboarded": true,
        "signupBy": { 
            "email": "john@example.com", 
            "firstName": "John", 
            "lastName": "Doe" 
        },
        "createdAt": "2022-04-05T10:07:08.235Z"
    }
}

Update an existing user

HTTP Request

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

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your app api key
x-tenant-id	string	Required	The tenant id

URL Parameters

Parameter	Description
USER_ID	The ID of the user

Body Parameters

Parameter	Type	Required	Description
role	string	Optional	The key for an existing Role
enabled	boolean	Optional	If the user should be able to access the tenant
teams	string[]	Optional	A tag for grouping the users

Response

HTTP 200

A Tenant user

Reset user password

Request example

await client.tenant('624c14cc0c01e70033356285').user('63cad6ac48dcba47e9322853').resetPassword()

curl --request POST 'https://account-api.nebulr-core.com/tenant/user/63cad6ac48dcba47e9322853/password' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'x-tenant-id: 624c14cc0c01e70033356285'

Response example:

Sends a password reset email to the given user.

HTTP Request

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

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your app api key
x-tenant-id	string	Required	The tenant id

URL Parameters

Parameter	Description
USER_ID	The ID of the user

Response

HTTP 201

Get the password reset link without sending an email:

Request example

await client.tenant('624c14cc0c01e70033356285').user('63cad6ac48dcba47e9322853').getResetPasswordLink()

curl --request GET 'https://account-api.nebulr-core.com/tenant/user/63cad6ac48dcba47e9322853/passwordLink' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'x-tenant-id: 624c14cc0c01e70033356285'

Response example:

https://app.nblocks.cloud/handover?appId=YOUR_APP_ID&flow=openidconnect&args=eyJlbnRyeVBvaW50IjoiL2F1dGgvc2V0LXBhc3N3b3JkLzA3YndwZjB1c2F1YW91aWZheHFlZm9tMnkxZ2lxb3l0eTlseDJxaGpwOGVubTF6MGtiNGR0M2hjYnpmdTJqbWljY3k2anYyazhiOG4xMG5pdXRtIn0=

HTTP Request

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

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your app api key
x-tenant-id	string	Required	The tenant id

URL Parameters

Parameter	Description
USER_ID	The ID of the user

Response

HTTP 200

Returns the password reset link as a string.

Delete user

Request example

await client.tenant('624c14cc0c01e70033356285').user('63cad6ac48dcba47e9322853').delete()

curl --request DELETE 'https://account-api.nebulr-core.com/tenant/user/63cad6ac48dcba47e9322853' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--header 'x-tenant-id: 624c14cc0c01e70033356285'

Delete an existing user.

HTTP Request

DELETE https://account-api.nebulr-core.com/tenant/user/:USER_ID

Headers

Parameter	Type	Required	Description
x-api-key	string	Required	Your app api key
x-tenant-id	string	Required	The tenant id

URL Parameters

Parameter	Description
USER_ID	The ID of the user

Response

HTTP 200

User management portal

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": {},
        "trial": false,
        "paymentStatus": {
            "shouldSelectPlan": false,
            "shouldSetupPayments": false,
            "provider": "STRIPE",
            "paymentsEnabled": true
        },
        "onboarded": true,
        "signupBy": { 
            "email": "john@example.com", 
            "firstName": "John", 
            "lastName": "Doe" 
        },
        "createdAt": "2021-04-05T12:20:54.890Z"
    },
    {
        "id": "605dd819e8fd3e00086cc552",
        "plan": "ESSENTIAL",
        "mfa": false,
        "locale": "en",
        "name": "Dave Ltd",
        "logo": "",
        "metadata": {},
        "trial": false,
        "paymentStatus": {
            "shouldSelectPlan": false,
            "shouldSetupPayments": false,
            "provider": "STRIPE",
            "paymentsEnabled": true
        },
        "onboarded": true,
        "signupBy": { 
            "email": "john@example.com", 
            "firstName": "John", 
            "lastName": "Doe" 
        },
        "federationConnection": "64c64cfb47418500082f60b5",
        "createdAt": "2021-03-26T12:48:25.187Z"
    }
]

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": "624c14cc0c01e70033356285",
    "plan": "TEAM",
    "trial": false,
    "paymentStatus": {
        "shouldSelectPlan": false,
        "shouldSetupPayments": false,
        "provider": "STRIPE",
        "paymentsEnabled": true
    },
    "mfa": false,
    "locale": "en",
    "name": "Nebulr AB",
    "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
    "metadata": {},
    "onboarded": true,
    "signupBy": { 
        "email": "john@example.com", 
        "firstName": "John", 
        "lastName": "Doe" 
    },
    "createdAt": "2022-04-05T10:07:08.235Z"
}

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": "624c14cc0c01e70033356285",
    "plan": "TEAM",
    "trial": false,
    "paymentStatus": {
        "shouldSelectPlan": false,
        "shouldSetupPayments": false,
        "provider": "STRIPE",
        "paymentsEnabled": true
    },
    "mfa": false,
    "locale": "en",
    "name": "Nebulr AB",
    "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
    "metadata": {},
    "onboarded": true,
    "signupBy": { 
        "email": "john@example.com", 
        "firstName": "John", 
        "lastName": "Doe" 
    },
    "createdAt": "2022-04-05T10:07:08.235Z"
}

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

Headers

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

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	Plan key. The plan must be present in the configured App business model
priceOffer	PriceOffer	Optional	One of the offering prices of the plan
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. Defaults to 'en'
logo	string	Optional	A URI to a logo. Can also be set by tenant owner during onboarding
onboarded	boolean	Optional	Is the tenant considered onboarded from start
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

PriceOffer

Parameter	Type	Required	Description
currency	string	Yes	Three-letter ISO currency code. Must be a supported currency. https://www.iso.org/iso-4217-currency-codes.html
recurrenceInterval	`'day', 'month', 'week', 'year'`	Yes	An interval for how often the customer will be charged for the subscription / plan.

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": "624c14cc0c01e70033356285",
    "plan": "TEAM",
    "trial": false,
    "paymentStatus": {
        "shouldSelectPlan": false,
        "shouldSetupPayments": false,
        "provider": "STRIPE",
        "paymentsEnabled": true
    },
    "mfa": false,
    "locale": "en",
    "name": "Nebulr AB",
    "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
    "metadata": {},
    "onboarded": true,
    "signupBy": { 
        "email": "john@example.com", 
        "firstName": "John", 
        "lastName": "Doe" 
    },
    "createdAt": "2022-04-05T10:07:08.235Z"
}

Update an existing tenant.

HTTP Request

PUT https://account-api.nebulr-core.com/tenant/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

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
logo	string	Optional	A URI to a logo.
mfa	boolean	Optional	Require users to login with MFA/2FA
onboarded	boolean	Optional	If this tenant is considered onboarded
federationConnection	string	Optional	Assign an existing Federation connection id to this tenant to activate enterprise login.
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

const response = await client.flag.evaluate("flag_1", {
        context: {
            user: {
                id: "63d2ab029e23db0afb07a5a7",
                role: "ADMIN",
                name: "John Doe",
                email: "john@doe.com",
                key: "custom-user-trait"
            },
            tenant: {
                id: "66238feb99227400774266f5",
                plan: "PREMIUM",
                name: "My Workspace",
                key: "custom-customer-trait",
            },
            device: {
                key: "iphone"
            },
            custom: {
                property1: "value1",
                property2: "value2",
                property3: "value2",
            }
        },
        accessToken: "XXXXXX"
    }
);

curl --request POST 'https://backendless.nblocks.cloud/flags/evaluate/605b603cfeb49f00082686b6/iphone-feature' \
--data-raw '{
    "context": {
        "user": {
            "id": "63d2ab029e23db0afb07a5a7",
            "role": "ADMIN",
            "name": "John Doe",
            "email": "john@doe.com",
            "key": "custom-user-trait"
        },
        "tenant": {
            "id": "66238feb99227400774266f5",
            "plan": "PREMIUM",
            "name": "My Workspace",
            "key": "custom-customer-trait",
        },
        "device": {
            "key": "iphone"
        },
        "custom": {
            "property1": "value1",
            "property2": "value2",
            "property3": "value2",
        }
    },
    "accessToken": "XXXXXX"
}'

Response example:

{
    "enabled": true
}

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

Instead of providing the user's access token you can send your own user context information to the evaluation api.

We recommend you to send as much information as possible from start for a flexible experience without the need for re-releases while you add more flags and conditions.

We've simplified this by defining a base structure of what information to send so you can more easily build your groups and conditions in Nblocks Admin.

The context object contains three areas, user, org and device. Each one of them reflect different traits and holds predefined relevant properties that you can assign. Additionally, there's a forth property custom which developers can send any key-values they like.

All areas also contain a property key which you can use to provide custom information if none of the others fits your need.
All these properties can easily be referenced when building the group targets you can define if the value should be equal (==), contain, beginsWith, endsWith, lessThan or greaterThan the value.

This context object can be that can be sent to /flags/evaluate and /flags/bulkEvaluate.

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

Body Parameters

Parameter	Type	Required	Description
context	Context	No	A context object
accessToken	string	No	A user access 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

const response = await client.flag.bulkEvaluate({
        context: {
            user: {
                id: "63d2ab029e23db0afb07a5a7",
                role: "ADMIN",
                name: "John Doe",
                email: "john@doe.com",
                key: "custom-user-trait"
            },
            tenant: {
                id: "66238feb99227400774266f5",
                plan: "PREMIUM",
                name: "My Workspace",
                key: "custom-customer-trait",
            },
            device: {
                key: "iphone"
            },
            custom: {
                property1: "value1",
                property2: "value2",
                property3: "value2",
            }
        },
        accessToken: "XXXXXX"
    }
);

curl --request POST 'https://backendless.nblocks.cloud/flags/bulkEvaluate/605b603cfeb49f00082686b6' \
--data-raw '{
    "context": {
        "user": {
            "id": "63d2ab029e23db0afb07a5a7",
            "role": "ADMIN",
            "name": "John Doe",
            "key": "custom-user-trait"
        },
        "org": {
            "id": "66238feb99227400774266f5",
            "plan": "PREMIUM",
            "name": "My Workspace",
            "key": "custom-customer-trait",
        },
        "device": {
            "key": "iphone"
        }
    },
    "accessToken": "XXXXXX"
}'

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

Instead of providing the user's access token you can send your own user context information to the evaluation api.

We recommend you to send as much information as possible from start for a flexible experience without the need for re-releases while you add more flags and conditions.

We've simplified this by defining a base structure of what information to send so you can more easily build your groups and conditions in Nblocks Admin.

All areas also contain a property key which you can use to provide custom information if none of the others fits your need.
All these properties can easily be referenced when building the group targets you can define if the value should be equal (==), contain, beginsWith, endsWith, lessThan or greaterThan the value.

This context object can be that can be sent to /flags/evaluate and /flags/bulkEvaluate.

HTTP Request

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

URL Parameters

Parameter	Description
APP_ID	Your app id

Body Parameters

Parameter	Type	Required	Description
context	Context	No	A context object
accessToken	string	No	A user access 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

const response = await client.flagAdmin.listSegments();

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/segments

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

const response = await client.flagAdmin.createSegment({
    key: "admins",
    description: "This segment targets admins",
    targets: [
        {
            user: {
                role: {
                    operator: "eq",
                    value: "ADMIN"
                }
            }
        }
    ]
});

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. Multiple targets must all match (logical AND) for the segment to match

Response

HTTP 200

Segment

Update a segment

Request example

const response = await client.flagAdmin.updateSegment("667447b583e592454b76d0ec", {
        description: 'This is a description'
    }
);

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. Multiple targets must all match (logical AND) for the segment to match

Response

HTTP 200

Segment

Delete a segment

Request example

await client.flagAdmin.deleteSegment("6674409b7bc7fe186ab98a56");

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

DELETE 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

const response = await client.flagAdmin.listFlags();

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/flags

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

const response = await client.flagAdmin.createFlag({
    key: "iphone-feature",
    description: "A feature for iPhones",
    defaultValue: false,
    segments: [
        "64c63e7adaf20f0008e71b20"
    ],
    targetValue: true,
    enabled: true
});

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. If any of the segment match (logical OR), the flag is 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

const response = await client.flagAdmin.updateFlag("667447b583e592454b76d0ec", {
        description: 'This is a description'
    }
);

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. If any of the segment match (logical OR), the flag is 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

await client.flagAdmin.deleteFlag("6674409b7bc7fe186ab98a56");

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

DELETE 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

Payments

Payments enable you to setup a business model and add a paywall to your app and start recieving money through subscriptions from your customers in matter of minutes.

Tenants will be able to subscribe to different Plans and you can use this information to tailor the user experience either manually or with Feature flags

If you connect a payment provider to your app, Nblocks will use that provider to collect and facitilate transactions using credit card, invoice, wallet and bank transfer payments.

List plans

Request example

const plans = await client.config.payments.listPlans();

curl --request GET 'https://account-api.nebulr-core.com/payments/plan' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "650c545529b15b62e681f282",
        "key": "free",
        "name": "Free",
        "trial": false,
        "trialDays": 0,
        "prices": [
            {
                "amount": 0,
                "currency": "EUR",
                "recurrenceInterval": "month"
            }
        ],
        "createdAt": "2023-09-21T14:33:57.810Z"
    },
    {
        "id": "650c548c29b15b62e681f28a",
        "key": "premium",
        "name": "Premium",
        "trial": true,
        "trialDays": 14,
        "prices": [
            {
                "amount": 50,
                "currency": "EUR",
                "recurrenceInterval": "month"
            }
        ],
        "createdAt": "2023-09-21T14:34:52.248Z"
    }
]

List all plans

HTTP Request

GET https://account-api.nebulr-core.com/payments/plan

Headers

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

Response

HTTP 200

List of Plans

Create a plan

Request example

const data = {
    name: "Premium",
    key: "premium", 
    description: "This is a premium plan for premium features", 
    trial: true, 
    trialDays: 14, 
    prices: [{
        {
            amount: 50,
            currency: "EUR",
            recurrenceInterval: "month"
        }
    }]
};
const newPlan = await client.config.payments.createPlan(data);

curl --request POST 'https://account-api.nebulr-core.com/payments/plan' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "name": "Premium",
    "key": "premium", 
    "description": "This is a premium plan for premium features", 
    "trial": true, 
    "trialDays": 14, 
    "prices": [{
        {
            "amount": 50,
            "currency": "EUR",
            "recurrenceInterval": "month"
        }
    }]
}'

Response example:

{
    "id": "650c548c29b15b62e681f28a",
    "key": "premium",
    "name": "Premium",
    "trial": true,
    "trialDays": 14,
    "prices": [
        {
            "amount": 50,
            "currency": "EUR",
            "recurrenceInterval": "month"
        }
    ],
    "createdAt": "2023-09-21T14:34:52.248Z"
}

Creates a plan that tenants can subscribe to

HTTP Request

POST https://account-api.nebulr-core.com/payments/plan

Headers

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

Body Parameters

Parameter	Type	Required	Description
key	string	Yes	Plan key, must be unique and cannot be changed. This is used identify the plan amongst subscribers and is used as argument during signup.
name	string	Yes	The name of the plan. Visible to customers
description	string	No	The description of the plan. Visible to customers
trial	bolean	No	If new subscribers should start with trial. When trialing, subscribers can subscribe to plans with costs without being charged
trialDays	number	No	The number of days before the trial expires
prices	Price[]	Yes	A list of prices which configures how this plan is offered

Response

HTTP 200

Plan

Get a plan

Request example

const plan = await client.config.payments.getPlan("PLAN_ID");

curl --request GET 'https://account-api.nebulr-core.com/payments/plan/PLAN_ID' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "id": "650c548c29b15b62e681f28a",
    "key": "premium",
    "name": "Premium",
    "trial": true,
    "trialDays": 14,
    "prices": [
        {
            "amount": 50,
            "currency": "EUR",
            "recurrenceInterval": "month"
        }
    ],
    "createdAt": "2023-09-21T14:34:52.248Z"
}

Get a plan

HTTP Request

GET https://account-api.nebulr-core.com/payments/plan/PLAN_ID

Headers

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

URL Parameters

Parameter	Description
PLAN_ID	The ID of the plan

Response

HTTP 200

Plan

Update a plan

Request example

const data = {
    trial: true, 
    trialDays: 14,
};
const updatedPlan = await client.config.payments.updatePlan("PLAN_ID", data);

curl --request PUT 'https://account-api.nebulr-core.com/payments/plan/PLAN_ID' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{ 
    "trial": true, 
    "trialDays": 14
}'

Response example:

{
    "id": "650c548c29b15b62e681f28a",
    "key": "premium",
    "name": "Premium",
    "trial": true,
    "trialDays": 14,
    "prices": [
        {
            "amount": 50,
            "currency": "EUR",
            "recurrenceInterval": "month"
        }
    ],
    "createdAt": "2023-09-21T14:34:52.248Z"
}

Updates an existing plan

HTTP Request

PUT https://account-api.nebulr-core.com/payments/plan/PLAN_ID

Headers

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

URL Parameters

Parameter	Description
PLAN_ID	The ID of the plan

Body Parameters

Parameter	Type	Required	Description
name	string	No	The name of the plan. Visible to customers
description	string	No	The description of the plan. Visible to customers
trial	bolean	No	If new subscribers should start with trial. When trialing, subscribers can subscribe to plans with costs without being charged
trialDays	number	No	The number of days before the trial expires
prices	Price[]	No	A list of prices which configures how this plan is offered

Response

HTTP 200

Plan

Delete a plan

Request example

await client.config.payments.deletePlan("PLAN_ID");

curl --request DELETE 'https://account-api.nebulr-core.com/payments/plan/PLAN_ID' \
--header 'x-api-key: YOUR_APP_API_KEY'

Delete an existing plan. Deleting a plan will not affect tenants already subscribing to this plan.

HTTP Request

DELETE https://account-api.nebulr-core.com/payments/plan/PLAN_ID

Headers

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

URL Parameters

Parameter	Description
PLAN_ID	The ID of the plan

Response

HTTP 200

List taxes

Request example

const taxes = await client.config.payments.listTaxes();

curl --request GET 'https://account-api.nebulr-core.com/payments/tax' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

[
    {
        "id": "650c55b8ac7f396d770a98b1",
        "countryCode": "DE",
        "name": "VAT",
        "percentage": 19,
        "createdAt": "2023-09-21T14:39:52.816Z"
    },
    {
        "id": "650c548c29b15b62e681f28a",
        "countryCode": "SE",
        "name": "MOMS",
        "percentage": 25,
        "createdAt": "2023-09-21T14:39:52.816Z"
    },
]

List all taxes

HTTP Request

GET https://account-api.nebulr-core.com/payments/tax

Headers

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

Response

HTTP 200

List of Taxes

Create a tax

Request example

const data = {
    countryCode: "DE",
    name: "VAT",
    percentage: 19
};
const newTax = await client.config.payments.createTax(data);

curl --request POST 'https://account-api.nebulr-core.com/payments/tax' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
    "countryCode": "DE",
    "name": "VAT",
    "percentage": 19
}'

Response example:

{
    "id": "650c55b8ac7f396d770a98b1",
    "countryCode": "DE",
    "name": "VAT",
    "percentage": 19,
    "createdAt": "2023-09-21T14:39:52.816Z"
}

Creates a tax for tenants from a specific country.

HTTP Request

POST https://account-api.nebulr-core.com/payments/tax

Headers

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

Body Parameters

Parameter	Type	Required	Description
countryCode	string	Yes	Two-letter ISO country code. https://www.nationsonline.org/oneworld/country_code_list.htm
name	string	Yes	Name of the tax. Visible to customers
percentage	string	Yes	Percentage with which the sub total is increased with. `0` - `100`

Response

HTTP 200

Tax

Get a tax

Request example

const tax = await client.config.payments.getTax("TAX_ID");

curl --request GET 'https://account-api.nebulr-core.com/payments/tax/TAX_ID' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "id": "650c55b8ac7f396d770a98b1",
    "countryCode": "DE",
    "name": "VAT",
    "percentage": 19,
    "createdAt": "2023-09-21T14:39:52.816Z"
}

Get a tax

HTTP Request

GET https://account-api.nebulr-core.com/payments/tax/TAX_ID

Headers

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

URL Parameters

Parameter	Description
TAX_ID	The ID of the tax

Response

HTTP 200

Tax

Update a tax

Request example

const data = {
    percentage: 19
};
const updatedTax = await client.config.payments.updateTax("TAX_ID", data);

curl --request PUT 'https://account-api.nebulr-core.com/payments/tax/TAX_ID' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{ 
    "percentage": 19
}'

Response example:

{
    "id": "650c55b8ac7f396d770a98b1",
    "countryCode": "DE",
    "name": "VAT",
    "percentage": 19,
    "createdAt": "2023-09-21T14:39:52.816Z"
}

Updates an existing tax

HTTP Request

PUT https://account-api.nebulr-core.com/payments/tax/TAX_ID

Headers

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

URL Parameters

Parameter	Description
TAX_ID	The ID of the tax

Body Parameters

Parameter	Type	Required	Description
countryCode	string	No	Two-letter ISO country code. https://www.nationsonline.org/oneworld/country_code_list.htm
name	string	No	Name of the tax. Visible to customers
percentage	string	No	Percentage with which the sub total is increased with. `0` - `100`

Response

HTTP 200

Tax

Delete a tax

Request example

await client.config.payments.deleteTax("TAX_ID");

curl --request DELETE 'https://account-api.nebulr-core.com/payments/tax/TAX_ID' \
--header 'x-api-key: YOUR_APP_API_KEY'

Delete an existing tax. Deleting a tax will not affect tenants already subscribing to plans.

HTTP Request

DELETE https://account-api.nebulr-core.com/payments/tax/TAX_ID

Headers

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

URL Parameters

Parameter	Description
TAX_ID	The ID of the tax

Response

HTTP 200

Connect to a payment provider

Nblocks uses Stripe as the payment provider to facilitate credit card, invoice, wallet and bank transfer payments. Nblocks will use your business model and create the required data in Stripe like Product, Prices and Taxes and keep this up to date.

See Update credentials how to provide your secret and public keys from Stripe to enable the integration.

Subscription portal - Select plan

This endpoint renders Nblocks hosted subscriptions views for selecting or managing subscriptions. Redirect the user agent or embedd this url into an iframe to render the view. Users will be able to select what plan to subscribe to. See Handover code for how to obtain the code parameter required for this call.

After the user has selected the plan, and provided setup payment information if required, the user will be redirected back to your app with new tokens.

HTTP Request

GET https://backendless.nblocks.cloud/subscription-portal/selectPlan?code=XXXX

URL Parameters

Parameter	Description
code	The code recieved from handover endpoint

Get tenant payment details

Request example

const details = await client.tenant(TENANT_ID).getPaymentDetails()

curl --request GET 'https://account-api.nebulr-core.com/tenant/TENANT_ID/paymentDetails' \
--header 'x-api-key: YOUR_APP_API_KEY'

Response example:

{
    "status": {
        "shouldSelectPlan": false,
        "shouldSetupPayments": true,
        "paymentsEnabled": true,
        "provider": "STRIPE"
    },
    "details": {
        "plan": {
            "id": "6516f55b900518015dc98f3e",
            "key": "premium",
            "name": "Premium",
            "description": "This is a premium plan",
            "trial": true,
            "trialDays": 15,
            "prices": [
                {
                    "amount": 100,
                    "currency": "EUR",
                    "recurrenceInterval": "month"
                }
            ],
            "createdAt": "2023-09-29T16:03:39.447Z"
        },
        "price": {
            "amount": 100,
            "currency": "EUR",
            "recurrenceInterval": "month"
        },
        "trial": false,
        "trialDaysLeft": 0
    }
}

Gets payment and subscriptions details about a specific tenant. This information is more in-depth than the status property attached to the Tenant.

HTTP Request

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

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 payment details

Set tenant plan details

Request example

const data = {
    planKey: "premium",
    priceOffer: {
        currency: "EUR",
        recurrenceInterval: "month"
    }
}
const details = await client.tenant(TENANT_ID).setPaymentDetails(data)

curl --request POST 'https://account-api.nebulr-core.com/tenant/TENANT_ID/paymentDetails' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{ 
    "planKey": "premium",
    "priceOffer": {
        "currency": "EUR",
        "recurrenceInterval": "month"
    }
}'

Response example:

{
    "status": {
        "shouldSelectPlan": false,
        "shouldSetupPayments": true,
        "paymentsEnabled": true,
        "provider": "STRIPE"
    },
    "details": {
        "plan": {
            "id": "6516f55b900518015dc98f3e",
            "key": "premium",
            "name": "Premium",
            "description": "This is a premium plan",
            "trial": true,
            "trialDays": 15,
            "prices": [
                {
                    "amount": 100,
                    "currency": "EUR",
                    "recurrenceInterval": "month"
                }
            ],
            "createdAt": "2023-09-29T16:03:39.447Z"
        },
        "price": {
            "amount": 100,
            "currency": "EUR",
            "recurrenceInterval": "month"
        },
        "trial": false,
        "trialDaysLeft": 0
    }
}

This endpoint let you manually change subscriptions details for a specific tenant. You can change the plan and/or the current price the tenant is subscribing to. If the app has enabled payment provider and tenant has setup payments this change will affect future transactions.

HTTP Request

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

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

Body Parameters

Parameter	Type	Required	Description
planKey	string	Yes	The key of the plan to subscribe to
priceOffer	PriceOffer	Yes	One of the offering prices of the plan

PriceOffer

Parameter	Type	Required	Description
currency	string	Yes	Three-letter ISO currency code. Must be a supported currency. https://www.iso.org/iso-4217-currency-codes.html
recurrenceInterval	`'day', 'month', 'week', 'year'`	Yes	An interval for how often the customer will be charged for the subscription / plan.

Response

HTTP 200

Tenant payment details

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 key of an existing plan
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	`'BCRYPT'`, `'ARGON2I'`, `'MD5'`, `'SHA1'`, `'SHA256'`, `'SHA512'`	Required	The algorithm that is being used.
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	`'BEGIN'` or `'END'`	Required	If the pepper should be prepended or appended the password.

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 key of an existing plan
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	`'BCRYPT'`, `'ARGON2I'`, `'MD5'`, `'SHA1'`, `'SHA256'`, `'SHA512'`	Required	The algorithm that is being used.
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	`'BEGIN'` or `'END'`	Required	If the pepper should be prepended or appended the password.

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": "624c14cc0c01e70033356285",
                "plan": "TEAM",
                "trial": false,
                "paymentStatus": {
                    "shouldSelectPlan": false,
                    "shouldSetupPayments": false,
                    "provider": "STRIPE",
                    "paymentsEnabled": false
                },
                "mfa": false,
                "locale": "en",
                "name": "Nebulr AB",
                "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
                "metadata": {},
                "onboarded": true,
                "signupBy": { 
                    "email": "john@example.com", 
                    "firstName": "John", 
                    "lastName": "Doe" 
                },
                "createdAt": "2022-04-05T10:07:08.235Z"
            }
        }
    ]
}

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": "624c14cc0c01e70033356285",
                "plan": "TEAM",
                "trial": false,
                "paymentStatus": {
                    "shouldSelectPlan": false,
                    "shouldSetupPayments": false,
                    "provider": "STRIPE",
                    "paymentsEnabled": false
                },
                "mfa": false,
                "locale": "en",
                "name": "Nebulr AB",
                "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
                "metadata": {},
                "onboarded": true,
                "signupBy": { 
                    "email": "john@example.com", 
                    "firstName": "John", 
                    "lastName": "Doe" 
                },
                "createdAt": "2022-04-05T10:07:08.235Z"
            }
        }
    ]
}

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"
                ],
                "lastSeen": "2023-01-20T18:00:12.489Z",
                "createdAt": "2023-01-20T18:00:12.489Z",
                "tenant": {
                    "id": "624c14cc0c01e70033356285",
                    "plan": "TEAM",
                    "trial": false,
                    "paymentStatus": {
                        "shouldSelectPlan": false,
                        "shouldSetupPayments": false,
                        "provider": "STRIPE",
                        "paymentsEnabled": true
                    },
                    "mfa": false,
                    "locale": "en",
                    "name": "Nebulr AB",
                    "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
                    "metadata": {},
                    "onboarded": true,
                    "signupBy": { 
                        "email": "john@example.com", 
                        "firstName": "John", 
                        "lastName": "Doe"  
                    },
                    "createdAt": "2022-04-05T10:07:08.235Z"
                }
            }
        }
    ]
}

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"
                ],
                "lastSeen": "2023-01-20T18:00:12.489Z",
                "createdAt": "2023-01-20T18:00:12.489Z",
                "tenant": {
                    "id": "624c14cc0c01e70033356285",
                    "plan": "TEAM",
                    "trial": false,
                    "paymentStatus": {
                        "shouldSelectPlan": false,
                        "shouldSetupPayments": false,
                        "provider": "STRIPE",
                        "paymentsEnabled": true
                    },
                    "mfa": false,
                    "locale": "en",
                    "name": "Nebulr AB",
                    "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
                    "metadata": {},
                    "onboarded": true,
                    "signupBy": { 
                        "email": "john@example.com", 
                        "firstName": "John", 
                        "lastName": "Doe" 
                    },
                    "createdAt": "2022-04-05T10:07:08.235Z"
                }
            }
        }
    ]
}

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"
                ],
                "lastSeen": "2023-01-20T18:00:12.489Z",
                "createdAt": "2023-01-20T18:00:12.489Z",
                "tenant": {
                    "id": "624c14cc0c01e70033356285",
                    "plan": "TEAM",
                    "trial": false,
                    "paymentStatus": {
                        "shouldSelectPlan": false,
                        "shouldSetupPayments": false,
                        "provider": "STRIPE",
                        "paymentsEnabled": true
                    },
                    "mfa": false,
                    "locale": "en",
                    "name": "Nebulr AB",
                    "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
                    "metadata": {},
                    "onboarded": true,
                    "signupBy": { 
                        "email": "john@example.com", 
                        "firstName": "John", 
                        "lastName": "Doe" 
                    },
                    "createdAt": "2022-04-05T10:07:08.235Z"
                }
            }
        }
    ]
}

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",
    "emailSenderName": "My App",
    "emailSenderEmail": "noreply@myapp.com",
    "webhookUrl": "http://api.example.com/webhook"
    "stripeEnabled": false,
    "paymentsAutoRedirect": true,
    "passkeysEnabled": true,
    "magicLinkEnabled": true,
    "mfaEnabled": true,
    "azureMarketplaceEnabled": false,
    "googleSsoEnabled": false,
    "azureAdSsoEnabled": true,
    "linkedinSsoEnabled": true,
    "githubSsoEnabled": true,
    "facebookSsoEnabled": true,
    "onboardingFlow": "B2B",
    "tenantSelfSignup": true,
    "cloudViews": true,
    "redirectUris": ["http://localhost:8080/auth/oauth-callback"],
    "defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
    "logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
    "websiteUrl": "http://localhost",
    "privacyPolicyUrl": "",
    "termsOfServiceUrl": "",
    "accessTokenTTL": 3600,
    "refreshTokenTTL": 604800
}

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
uiUrl	string	URL to your frontend app (for onboarding redirects etc).
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
paymentsAutoRedirect	boolean	Activates redirect to select payments plans and takes a user to selection of payment plans directly after signup or after a trial has ended.
stripeEnabled	boolean	Boolean value telling the user if Stripe is enabled
passkeysEnabled	boolean	Boolean value telling the user if Login with Passkeys is enabled
magicLinkEnabled	boolean	Boolean value telling the user if Login with Magic-Link is enabled
mfaEnabled	boolean	Boolean value telling the user if multi-factor authentication is enabled
azureMarketplaceEnabled	boolean	Boolean value telling the user if Azure marketplace is enabled
googleSsoEnabled	boolean	Boolean value telling the user if Login with Google SSO is enabled
linkedinSsoEnabled	boolean	Boolean value telling the user if Login with LinkedIn SSO is enabled
githubSsoEnabled	boolean	Boolean value telling the user if Login with Github SSO is enabled
facebookSsoEnabled	boolean	Boolean value telling the user if Login with Facebook SSO is enabled
azureAdSsoEnabled	boolean	Boolean value telling the user if Login with Azure SSO is enabled
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
tenantSelfSignup	boolean	Wheater to allow users to signup for new workspaces themselves
redirectUris	string[]	Allowed redirect uris
defaultCallbackUri	string	Default handover/callback uri used by Nblocks
accessTokenTTL	number	Access token lifetime in seconds
refreshTokenTTL	number	Refresh token lifetime seconds

Credentials state model

Model example:

{
    "stripeCredentialsAdded": true,
    "azureMarketplaceCredentialsAdded": true,
    "azureAdSsoCredentialsAdded": false,
    "googleSsoCredentialsAdded": true
}

Parameter	Type	Description
stripeCredentialsAdded	boolean	If `stripeSecretKey` and `stripePublicKey` exist
azureMarketplaceCredentialsAdded	boolean	If `microsoftAzureMarketplaceClientId`, `microsoftAzureMarketplaceClientSecret`, and `microsoftAzureMarketplaceTenantId` exist
azureAdSsoCredentialsAdded	boolean	If `microsoftAzureADClientId`, `microsoftAzureADClientSecret`, and `microsoftAzureADTenantId` exist
googleSsoCredentialsAdded	boolean	If `googleClientId` and `googleClientSecret` exist

Tenant model

Model example:

{
    "id": "624c14cc0c01e70033356285",
    "plan": "TEAM",
    "trial": false,
    "paymentStatus": {
        "shouldSelectPlan": false,
        "shouldSetupPayments": false,
        "provider": "STRIPE",
        "paymentsEnabled": true
    },
    "mfa": false,
    "locale": "en",
    "name": "Nebulr AB",
    "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
    "metadata": {},
    "onboarded": true,
    "signupBy": { 
        "email": "john@example.com", 
        "firstName": "John", 
        "lastName": "Doe" 
    },
    "createdAt": "2022-04-05T10:07:08.235Z"
}

Parameter	Type	Description
id	string	Unique ID (Read only)
plan	string	Plan key. Tells what plan the tenant is subscribing to. See Plan model
trial	boolean	The tenant is currently trialing on the selected plan
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
paymentStatus	Payment status	The tenant current payment status
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
federationConnection	string	Assigned Federation connection id used for authentication. Part of Enterprise login.
signupBy	Object	Object containing email and name on the first tenant owner that was used when creating / signing up the new tenant
createdAt	string	Timestamp when created (Read only)

Tenant payment status

Model example:

{
    "shouldSelectPlan": false,
    "shouldSetupPayments": false,
    "provider": "STRIPE",
    "paymentsEnabled": true
}

Parameter	Type	Description
shouldSelectPlan	boolean	The tenant should immediately select a plan. Redirect the owner to Subscription portal / select plan
shouldSetupPayments	boolean	The tenant should setup payment immediately because tenant has not setup payments and the subscribing plan carry a cost and the trial has ended. Redirect the owner to Subscription portal / select plan
paymentsEnabled	boolean	Payment method has been set up. Nblocks can bill this tenant
provider	string	The provider used for this tenant

Tenant payment details

More in depth details about a tenants payment and subscription

Model example:

{
    "status": {
        "shouldSelectPlan": false,
        "shouldSetupPayments": true,
        "paymentsEnabled": true,
        "provider": "STRIPE"
    },
    "details": {
        "plan": {
            "id": "6516f55b900518015dc98f3e",
            "key": "premium",
            "name": "Premium",
            "description": "This is a premium plan",
            "trial": true,
            "trialDays": 15,
            "prices": [
                {
                    "amount": 100,
                    "currency": "EUR",
                    "recurrenceInterval": "month"
                }
            ],
            "createdAt": "2023-09-29T16:03:39.447Z"
        },
        "price": {
            "amount": 100,
            "currency": "EUR",
            "recurrenceInterval": "month"
        },
        "trial": false,
        "trialDaysLeft": 0
    }
}

Parameter	Type	Description
status	Tenant payment status	Current payment status
details	Tenant plan Details	Details about the plan this tenant is subscribing to

Tenant plan details

Model example:

{
    "plan": {
        "id": "6516f55b900518015dc98f3e",
        "key": "premium",
        "name": "Premium",
        "description": "This is a premium plan",
        "trial": true,
        "trialDays": 15,
        "prices": [
            {
                "amount": 100,
                "currency": "EUR",
                "recurrenceInterval": "month"
            }
        ],
        "createdAt": "2023-09-29T16:03:39.447Z"
    },
    "price": {
        "amount": 100,
        "currency": "EUR",
        "recurrenceInterval": "month"
    },
    "trial": false,
    "trialDaysLeft": 0
}

Parameter	Type	Description
plan	Plan	The plan this tenant subscribes to
price	Price	The price within the plan this tenant subscribes to
trial	boolean	If this tenant is currently trialing
trialDaysLeft	number	The number of days left until trial ends for this tenant

Tenant user model

Model example:

{
    "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"
    ],
    "lastSeen": "2023-01-20T18:00:12.489Z",
    "createdAt": "2023-01-20T18:00:12.489Z",
    "tenant": {
        "id": "624c14cc0c01e70033356285",
        "plan": "TEAM",
        "trial": false,
        "paymentStatus": {
            "shouldSelectPlan": false,
            "shouldSetupPayments": false,
            "provider": "STRIPE",
            "paymentsEnabled": true
        },
        "mfa": false,
        "locale": "en",
        "name": "Nebulr AB",
        "logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
        "metadata": {},
        "onboarded": true,
        "signupBy": { 
            "email": "john@example.com", 
            "firstName": "John", 
            "lastName": "Doe" 
        },
        "createdAt": "2022-04-05T10:07:08.235Z"
    }
}

Parameter	Type	Description
id	string	Unique ID (Read only)
role	string	Role of the user. Grants a set of privileges. The set of privileges is configured on the `Role` 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
lastSeen	string	Timestamp for last user activity (Read only)
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

Model example:

{
  "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 key

Id token model

Model example:

{
  "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

Access role model

Model example:

{
    "id": "6516a01891eca485bfc230ba",
    "name": "Owner",
    "key": "OWNER",
    "description": "The owner of the app",
    "privileges": [
        {
            "id": "6516a0ee38183223122704e3",
            "key": "AUTHENTICATED",
            "description": "Privilege for all authenticated users"
        }
    ],
    "isDefault": false
}

Parameter	Type	Description
id	string	Unique ID (Read only)
name	string	Role name. Presentable label of the role
key	string	Role key. Use this to reference the role in the `Tenant user` model
description	string	Description text
privileges	Privileges[]	The set of privileges linked to this role
isDefault	boolean	If a role is default it will be applied to new tenant users. Only one role can be the default.

Access privilege model

Model example:

{
    "id": "6516a0ee38183223122704e3",
    "key": "AUTHENTICATED",
    "description": "Privilege for all authenticated users"
}

Parameter	Type	Description
id	string	Unique ID (Read only)
key	string	Privilege key. Use this to evaluate and grant user access
description	string	Description text

Federation connection model

Model example:

[
    {
        "id": "6571edf9dc018000227ac449",
        "type": "saml",
        "name": "Foobar SAML",
        "clientId": "client_1234",
        "loginUrl": "https://anotherIdP.com/api/saml/sso",
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END CERTIFICATE-----",
        "requestMethod": "POST",
        "signedRequest": true,
        "signedRequestAlgorithm": "sha256",
        "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIC4jCCAcoCCQC33wuiuSThHpLKQQ==\n-----END PRIVATE KEY-----",
        "createdAt": "2023-12-07T16:08:25.061Z"
    }
]

Parameter	Type	Description
id	string	Unique ID (Read only)
type	`saml`	The connection type. `saml` is the only supported type currently.
name	string	A connection name. This will also be visible for users when logging in
clientId	string	The identifier assigned to your application by the IdP. This is sometimes not required
loginUrl	string	The URL where the IdP expects to receive SAML authentication requests
certificate	string	The public key certificate provided by the IdP to validate the SAML responses.
requestMethod	`GET` or `POST`	The preferred method for sending SAML requests, either HTTP GET Redirect (most common) or HTTP POST.
signedRequest	boolean	Whether the IdP requires the SAML request to be signed or not.
signedRequestAlgorithm	`sha256` or `sha512`	Request signing algorithm
privateKey	string	Request signing private key. The public key should be handover to IdP
createdAt	string	Timestamp when created (Read only)

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

Plan model

Model example:

{
    "id": "650c548c29b15b62e681f28a",
    "key": "premium",
    "name": "Premium",
    "trial": true,
    "trialDays": 14,
    "prices": [
        {
            "amount": 50,
            "currency": "EUR",
            "recurrenceInterval": "month"
        }
    ],
    "createdAt": "2023-09-21T14:34:52.248Z"
}

Parameter	Type	Description
id	string	Unique ID (Read only)
key	string	Plan key, must be unique and cannot be changed. This is used identify the plan amongst subscribers and is used as argument during signup.
name	string	The name of the plan. Visible to customers
trial	string	If new subscribers should start with trial. When trialing, subscribers can subscribe to plans with costs without being charged
trialDays	number	The number of days before the trial expires
prices	Price[]	A list of prices which configures how this plan is offered
createdAt	string	Timestamp when created (Read only)

Price model

Model example:

{
    "amount": 50,
    "currency": "EUR",
    "recurrenceInterval": "month"
}

Parameter	Type	Description
amount	number	The amount for each recurring charge
currency	string	Three-letter ISO currency code. Must be a supported currency. https://www.iso.org/iso-4217-currency-codes.html
recurrenceInterval	`'day', 'month', 'week', 'year'`	An interval for how often the customer will be charged for the subscription / plan.

Tax model

Model example:

{
    "id": "650c55b8ac7f396d770a98b1",
    "countryCode": "DE",
    "name": "VAT",
    "percentage": 19,
    "createdAt": "2023-09-21T14:39:52.816Z"
}

Parameter	Type	Description
id	string	Unique ID (Read only)
countryCode	string	Two-letter ISO country code. https://www.nationsonline.org/oneworld/country_code_list.htm
name	string	Name of the tax. Visible to customers
percentage	number	Percentage with which the sub total is increased with. `0` - `100`
createdAt	string	Timestamp when created (Read only)

Feature flags evaluation context

Fields marked in bold text will be auto resolved by Nblocks when providing a user access token.

Model example:

{
    "user": {
        "id": "63d2ab029e23db0afb07a5a7",
        "role": "ADMIN",
        "name": "John Doe",
        "email": "john@doe.com",
        "key": "custom-user-trait"
    },
    "tenant": {
        "id": "66238feb99227400774266f5",
        "plan": "PREMIUM",
        "name": "My Workspace",
        "key": "custom-customer-trait",
    },
    "device": {
        "key": "iphone"
    },
    "custom": {
        "property1": "value1",
        "property2": "value2",
        "property3": "value2",
    }
}

Parameter	Type	Description
user	UserContext	User context
tenant	TenantContext	Tenant context
device	KeyContext	Device context
device	KeyContext	Device context
custom	CustomContext	Custom context

UserContext

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

TenantContext

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

KeyContext

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

CustomContext

The custom property is a map that allows developers to include any additional custom key-value pairs. Each key in the custom object should be a string, and the corresponding value should also be a string.

Parameter	Type	Description
key	string	Custom property name defined by the developer
value	string	Value associated with the custom property name

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"
        }
    },
    "custom": {
        "property1": {
            "operator": "lessThan",
            "value": "2"
        },
        "property2": {
            "operator": "contains",
            "value": "foobar"
        }
    }
}

Parameter	Type	Description
user	UserTarget	Conditions on user level
tenant	TenantTarget	Conditions on tenant level
device	KeyTarget	Conditions on device level
custom	CustomTarget	Custom conditions

UserTarget

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

TenantTarget

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

CustomTarget

The custom property is a map that allows developers to include any additional custom key and pair it a TargetValue. Each key in the custom object should be a string, and the corresponding value should be a TargetValue.

Parameter	Type	Description
key	string	Custom property name defined by the developer
value	TargetValue	Value associated with the custom property 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
lessThan	It should be less than the value
greaterThan	It should be greater than 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	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

4 August 2024

Improved user Tokens

Added more claims to accessToken and idToken.
Nblocks now exposes an onboarded property that can be set on both user and tenant level.

12 July 2024

Feature flags improvements

Introducing new operators lowerThan and greaterThan
Made it simpler to build AND / OR conditions with segments and flags.
Adding user email condition and context
Adding Custom context that allow developers to include any additional custom key-value pairs

Manage subscriptions in Nblocks Admin

Change workspace subscriptions directly from Nblocks Admin

18 June 2024

Stability & Performance improvements

General performance improvements throught out all Nblocks APIs.
Nblocks React plugin: Adding greater support for older versions of React.

7 June 2024

Added toggle to either enable or disable user self signup through Nblocks UI.

19 May 2024

Adding Facebook & Github connections

User can now authenticate with Magic-link.

4 May 2024

New React plugin

Launching a new React plugin for a smoother Nblocks experience with React.

16 April 2024

Improved Nblocks Admin

Updates and improvements made to the interactive onboarding models in Nblocks Admin
Invite team members to your workspace to collaborate on apps

You can now activate LinkedIn as a Social Login alternative.

23 March 2024

Logout via Auth Service

A new logout endpoint made available to completely logout a user from OAuth 2.0 / OIDC flows.

21 Feb 2024

Delete tenants and apps

Tenants can now be completely deleted including its users and data.
Apps can also be deleted and will delete data and its tenants.
Delete operations can be initiated both from Nblocks Admin and via Rest APIs.

20 December 2023

Adding SAML support as a new alternative login method
SAML can be setup using federation connections
Federation connection can be assigned to tenants as their primary login method

Password reset flow

Admins can now more efficiently handle password reset requests

10 December 2023

Nblocks Admin interactive onboarding

It's now easier to integrate different Nblocks modules with ready made code snippets and interactive onboarding.

28 November 2023

Adding customizations to Nblocks Admin

Configure app properties such as name and logo
Create a custom theme for Nblocks hosted views
Set the sender name and email address for emails sent from Nblocks

Breaking changes:

https://backendless.nblocks.cloud
- CSS endpoints are moved to https://admin-api.nblocks.cloud

23 October 2023

Payments Launch

Introducing Payments feature for seamless integration with billing providers to get paid while building with Nblocks.
Use pre-made components and build paywalls in no time.
Generate signup links to specific plans

9 October 2023

Improved access controll

Enhancements to Roles and Privileges settings and simple configuration via Nblocks Admin.
Additional authentication options to fine-tune your users application access.

29 September 2023

Passkeys support

Strengthen your application security with Passkeys support for Nblocks login.

6 September 2023

Streamlined Signup Flow for your new users
Initiate signup flow via link

16 August 2023

Feature Flags

Unveiling the Feature Flags functionality for controlled feature rollouts and experimentation.

July 2023

Branding for User Management Portal

Personalize your User Management Portal with custom CSS and translations.

June 2023

Embedding User Management Portal

Seamlessly integrate the User Management Portal into your applications.
Google Single Sign-On (SSO)

May 2023

Azure AD SSO and Marketplace Integration

Introducing Azure AD Single Sign-On and seamless integration with the Azure Marketplace.
Trial Support for your application Plans

April 2023

Improved Onboarding Information

Enhance user onboarding with improved information.
onboarded Properties
Tailor a smoother onboarding experience with the addition of onboarded properties to both tenantUser and tenant objects.

March 2023

Brandable Email Templates

Customize your branding with brandable email templates.
Communication API Enhancements
Empower developers to change default email templates, achieving a fully customized branding experience.

October 2023

Launch of Payments
Improvements to Roles and privileges
Adding more granular control for authentication options

September 2023

Passkeys support for Nblocks login
Added signup flow

August 2023

Launch of Feature flags.

July 2023

Brandning of User management portal with CSS and translations

June 2023

Support for embedding User management portal
Google SSO

May 2023

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

April 2023

Improving onboarding information
Adding the onboarded properties to both tenantUser and tenant objects so it's simpler to tailor a good onboarding.

March 2023

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

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:

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

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 Nblocks app

Creating via Nblocks Admin

Creating via terminal

App Profile

Get app profile

HTTP Request

Headers

Response

Update app profile

HTTP Request

Body Parameters

Response

Update credentials

HTTP Request

Body Parameters

Response

Get credentials state

HTTP Request

Headers

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

Delete 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