Start
This documentation describes the all functionality available through the HTTP REST api and the available low level clients that wraps this functionality for different programming languages.
All calls to Nblocks are encrypted over HTTPS.
If you wish to go back to the high level and plug-n-play documentation click here
Authentication
How it works
Request example with api key
const client = new NblocksClient(YOUR_APP_API_KEY);
await new client.some.cool.function();
curl --request GET 'https://someapi.com/endpoint' \
--header 'x-api-key: YOUR_APP_API_KEY'
All calls to Nblocks apis requires you to authorize yourself as a valid app, either with your unique App ID or more commonly your secret API key. You should have received these keys upon registration. The apis expect you to authorize each call by including your api key in the HTTP headers.
x-api-key: YOUR_APP_API_KEY
This should not be confused with your users authenticating. When they login into your app they authenticate with their own credentails using a Oauth 2.0 flow.
Registrating for a new app profile
npx @nebulr-group/nblocks-cli create-app
The NPX tool will create a new folder and place a .env
file containing your Nblocks API key and download a copy of your app profile into a file app-configuration.json
. Use this API key from the env file and the App ID from your app profile to start calling our APIs.
App Profile
As the developer, the App profile is your entrypoint to Nblocks. This is your unique set of settings to tailor the Nblocks experience. You can have several different Profiles, e.g. one for production and one for testing. This helps organize and separate configurations from different stages in your development process.
Get app profile
Request example
const response = await client.config.getAppProfile();
curl --request GET 'https://account-api.nebulr-core.com/app' \
--header 'x-api-key: YOUR_APP_API_KEY'
Response example:
{
"id": "624c14cc0c01e70033356282",
"name": "My app",
"domain": "MY_APP",
"apiUrl": "http://localhost:3000",
"uiUrl": "http://localhost:8100",
"webhookUrl": "http://api.example.com/webhook"
"stripeEnabled": false,
"passkeysEnabled": true,
"azureMarketplaceEnabled": false,
"googleSsoEnabled": false,
"azureAdSsoEnabled": true,
"onboardingFlow": "B2B",
"cloudViews": true,
"redirectUris": ["http://localhost:8080/auth/oauth-callback"],
"defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
"defaultRole": "OWNER",
"roles": {
"OWNER": [
"AUTHENTICATED",
"TENANT_READ",
"TENANT_WRITE",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"TAG_WRITE",
"USER_READ",
"USER_WRITE",
"GROUP_WRITE",
"GROUP_READ",
"ASSIGNEES_WRITE",
"SETTINGS_READ",
"SETTINGS_WRITE"
],
"ADMIN": [
"AUTHENTICATED",
"TENANT_READ",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"TAG_WRITE",
"USER_READ",
"USER_WRITE",
"GROUP_WRITE",
"GROUP_READ",
"ASSIGNEES_WRITE",
"SETTINGS_READ",
"SETTINGS_WRITE"
],
"MANAGER": [
"AUTHENTICATED",
"TENANT_READ",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"USER_READ",
"GROUP_READ",
"SETTINGS_READ"
],
},
"businessModel": {
"taxes": [
{
"region": "SE",
"name": "VAT",
"percentage": 25
}
],
"plans": [
{
"name": "ESSENTIAL",
"prices": [
{
"region": "SE",
"amount": 500,
"currency": "SEK",
"recurrenceInterval": "month"
},
{
"region": "DE",
"amount": 50,
"currency": "EUR",
"recurrenceInterval": "month"
}
]
},
{
"name": "TEAM",
"trialDays": 14,
"prices": [
{
"region": "SE",
"amount": 1000,
"currency": "SEK",
"recurrenceInterval": "month"
},
{
"region": "DE",
"amount": 100,
"currency": "EUR",
"recurrenceInterval": "month"
}
]
}
]
},
"logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
"websiteUrl": "http://localhost",
"privacyPolicyUrl": "",
"termsOfServiceUrl": ""
}
Gets the complete App
model of your app.
The app is your top most entity and holds all configurations for how your App interacts with the platform in any sub call.
Use this response data to alter your model and push back.
HTTP Request
GET https://account-api.nebulr-core.com/app
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Response
HTTP 200
Your App profile model
Update app profile
Request example
const response = await client.config.updateAppProfile({logo: "https://www.example.com/another_logo.png"});
curl --request PUT 'https://account-api.nebulr-core.com/app' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"logo": "https://www.example.com/another_logo.png"
}'
Response example:
{
"id": "624c14cc0c01e70033356282",
"name": "My app",
"domain": "MY_APP",
"apiUrl": "http://localhost:3000",
"uiUrl": "http://localhost:8100",
"webhookUrl": "http://api.example.com/webhook"
"stripeEnabled": false,
"passkeysEnabled": true,
"azureMarketplaceEnabled": false,
"googleSsoEnabled": false,
"azureAdSsoEnabled": true,
"onboardingFlow": "B2B",
"cloudViews": true,
"redirectUris": ["http://localhost:8080/auth/oauth-callback"],
"defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
"defaultRole": "OWNER",
"roles": {
"OWNER": [
"AUTHENTICATED",
"TENANT_READ",
"TENANT_WRITE",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"TAG_WRITE",
"USER_READ",
"USER_WRITE",
"GROUP_WRITE",
"GROUP_READ",
"ASSIGNEES_WRITE",
"SETTINGS_READ",
"SETTINGS_WRITE"
],
"ADMIN": [
"AUTHENTICATED",
"TENANT_READ",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"TAG_WRITE",
"USER_READ",
"USER_WRITE",
"GROUP_WRITE",
"GROUP_READ",
"ASSIGNEES_WRITE",
"SETTINGS_READ",
"SETTINGS_WRITE"
],
"MANAGER": [
"AUTHENTICATED",
"TENANT_READ",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"USER_READ",
"GROUP_READ",
"SETTINGS_READ"
],
},
"businessModel": {
"taxes": [
{
"region": "SE",
"name": "VAT",
"percentage": 25
}
],
"plans": [
{
"name": "ESSENTIAL",
"prices": [
{
"region": "SE",
"amount": 500,
"currency": "SEK",
"recurrenceInterval": "month"
},
{
"region": "DE",
"amount": 50,
"currency": "EUR",
"recurrenceInterval": "month"
}
]
},
{
"name": "TEAM",
"trialDays": 14,
"prices": [
{
"region": "SE",
"amount": 1000,
"currency": "SEK",
"recurrenceInterval": "month"
},
{
"region": "DE",
"amount": 100,
"currency": "EUR",
"recurrenceInterval": "month"
}
]
}
]
},
"logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
"websiteUrl": "http://localhost",
"privacyPolicyUrl": "",
"termsOfServiceUrl": ""
}
You can update the app with the same JSON you got from Get app model
or just provide the field you want to update
HTTP Request
PUT https://account-api.nebulr-core.com/app
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Optional | Name of the app |
apiUrl | string | Optional | URL to your api (to receive webhooks etc). |
defaultRole | string | Optional | Default user role |
uiUrl | string | Optional | URL to your frontend app (for onboarding redirects etc). |
webhookUrl | string | Optional | Enable webhook and events to be sent to this url |
roles | Record |
Optional | All user roles and their granted privileges |
businessModel | BusinessModel | Optional | The business model defines what plans are available to subscribe to and what taxes applies. |
logo | string | Optional | URL to your logo |
websiteUrl | string | Optional | URL to your website or landing page. E.g. Branded emails will link to this URL, checkout process will redirect to /payment-success and /payment-cancel |
privacyPolicyUrl | string | Optional | URL to a page on your website containing a Privacy policy for your app users. E.g. checkout process will link to this url. |
termsOfServiceUrl | string | Optional | URL to a page on your website containing a Terms of service for your app users. E.g. checkout process will link to this url. |
emailSenderName | string | Optional | Emails sent from Nblocks will have this sender name |
emailSenderEmail | string | Optional | Emails sent from Nblocks will have this sender email. You'll have to verify this email before |
onboardingFlow | OnboardingFlow | Optional | Configure how users will be onboarded |
cloudViews | boolean | Optional | Toggle this to true if you want to use a UI provided by NBlocks instead of your own |
redirectUris | string[] | Optional | Allowed redirect uris |
defaultCallbackUri | string | Optional | Default handover/callback uri used by Nblocks |
Response
HTTP 200
Your App profile model
Update credentials
Request example
const response = await client.config.updateCredentials({
googleClientId: "XXXXXXX",
googleClientSecret: "XXXXXXX"
});
curl --request PUT 'https://account-api.nebulr-core.com/app/credentials' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"googleClientId": "XXXXXXX",
"googleClientSecret": "XXXXXXX"
}'
Store sensitive credentials for your app so NBlocks can authorize with 3d party services on your behalf.
These credentials are never outputted back again
E.g. Stripe integration, social login providers like Google, Facebook, Github etc.
HTTP Request
PUT https://account-api.nebulr-core.com/app/credentials
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
stripeSecretKey | string | Optional | Stripe integration, secret key |
stripePublicKey | string | Optional | Stripe integration, public key |
microsoftAzureMarketplaceClientId | string | Optional | Microsoft Azure Marketplace integration App |
microsoftAzureMarketplaceClientSecret | string | Optional | Microsoft Azure Marketplace integration App |
microsoftAzureMarketplaceTenantId | string | Optional | Microsoft Azure Marketplace integration App |
googleClientId | string | Optional | Google social login |
googleClientSecret | string | Optional | Google social login |
githubClientId | string | Optional | Gitlab social login |
githubClientSecret | string | Optional | Gitlab social login |
facebookAppId | string | Optional | Facebook social login |
facebookAppSecret | string | Optional | Facebook social login |
microsoftAzureADClientId | string | Optional | MS Azure AD SSO |
microsoftAzureADClientSecret | string | Optional | MS Azure AD SSO |
microsoftAzureADTenantId | string | Optional | MS Azure AD SSO |
Response
HTTP 200
Branding
You can change the looks of Nblocks by changing your app's branding.
Nblocks supports these different kinds of branding.
- Custom email templates for emails sent to your users via Nblock
- Custom CSS for the Nblocks hosted views that you embedd in your application
- Custom translations for the Nblocks hosted views that you embedd in your application
Set custom email template
Request example
TBD
curl --request PUT 'https://communication-api.nebulr-core.com/template/SIGNUP' \
--header 'x-api-key: YOUR_APP_API_KEY'
--data-raw '{
"type": "SIGNUP",
"testRecipient": "john@doe.com",
"content": "<h1>Signup</h1><a href=\"{{ctaUrl}}\">Click here</a>"
}'
Overriding one of the pre defined templates can be done easily. When you override a template, Nblocks will use this content for all languages.
Templates | Description |
---|---|
RESET-PASSWORD | Sent to the user when the user requests to set a new password |
SIGNUP | Sent when a user sign up for a new tenant |
INVITE_NEW | Sent when a new user is invited to a tenant |
INVITE_EXISTING | Sent when an existing user of other tenants are invited to a tenant |
PAYMENT_FAILURE | Sent to the tenant owner if in case of any subscription payment failures |
BASE | This template is used when you send transactional emails yourself through the api. |
The HTML content supports variables that are injected when rendering the template. Except for the ctaUrl
variable, which contains a unique link if the mail asks the user to perform an action, these are not required and can be considered just as helpers.
Variables in themplates, use <h1>{{variable}}</h1>
to inject it in the content html.
Variable | Example | Description |
---|---|---|
appName | My app |
Your app name |
appLogo | https://url-to-logo.png |
Your app logo url |
appUrl | https://url-to-app.com |
A url to your app frontend |
emailTitle | Reset your password |
The title of the email. Comes from Nblocks standard texts |
emailBody | To reset your password, please click the button... |
The content of the email. Comes from Nblocks standard texts |
ctaTitle | Reset password |
The Call-to-action button title. Comes from Nblocks standard texts |
ctaUrl | https://unique-link... |
The Call-to-action button link. A unique link relevant to this email |
fallBackButtonText | Button not working? Click the li... |
A title to a fallback link displayed under the CTA button for older email clients |
currentYear | 2023 |
Current year |
HTTP Request
PUT https://communication-api.nebulr-core.com/template/:templateName
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
URL Parameters
Parameter | Description |
---|---|
templateName | Any of the available template names listed above |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
type | string | Yes | Any of the available template names listed above |
testRecipient | string | No | If provided, Nblocks will send a test email with the updated template |
content | string | Yes | The template content in HTML |
Response
HTTP 200
Get custom email template
Request example
TBD
curl --request GET 'https://communication-api.nebulr-core.com/template/SIGNUP' \
--header 'x-api-key: YOUR_APP_API_KEY'
Response example:
{
"type": "SIGNUP",
"content": "<h1>Signup</h1><a href=\"{{ctaUrl}}\">Click here</a>"
}
Get a custom email template
HTTP Request
GET https://communication-api.nebulr-core.com/template/:templateName
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
URL Parameters
Parameter | Description |
---|---|
templateName | Any of the available template names listed in set custom email template |
Response
HTTP 200
Parameter | Type | Description |
---|---|---|
type | string | The template name |
content | string | The template content in HTML |
Delete custom email template
Request example
TBD
curl --request DELETE 'https://communication-api.nebulr-core.com/template/SIGNUP' \
--header 'x-api-key: YOUR_APP_API_KEY'
Deleting a custom template will restore Nblocks default template.
HTTP Request
DELETE https://communication-api.nebulr-core.com/template/:templateName
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
URL Parameters
Parameter | Description |
---|---|
templateName | Any of the available template names listed in set custom email template |
Response
HTTP 200
Set custom CSS
Request example
TBD
curl --request POST 'https://backendless.nblocks.cloud/brand/css' \
--header 'x-api-key: YOUR_APP_API_KEY'
--data-raw '{
"content": "html,body { background-color: red !important; }"
}'
The CSS is used by Nblocks Cloud views, like Nblocks Login and User Management portal. Use the example css as a base to start set your own brand.
HTTP Request
POST https://backendless.nblocks.cloud/brand/css
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
content | string | Yes | The CSS content |
Response
HTTP 200
Get your custom CSS
Request example
TBD
curl --request GET 'https://backendless.nblocks.cloud/brand/css' \
--header 'x-api-key: YOUR_APP_API_KEY'
Response example:
{
"content": "html,body { background-color: red !important; }"
}
The CSS is used by Nblocks Cloud views, like Nblocks Login and User Management portal.
HTTP Request
GET https://backendless.nblocks.cloud/brand/css
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Response
HTTP 200
Parameter | Type | Description |
---|---|---|
content | string | The CSS content |
Set custom Translations
Request example
TBD
curl --request POST 'https://backendless.nblocks.cloud/brand/translations' \
--header 'x-api-key: YOUR_APP_API_KEY'
--data-raw '{
"Login": "Log in",
"Email address": "Email"
}'
The translations are used by Nblocks Cloud views, like Nblocks Login and User Management portal. Use this template to understand what translations can be changed.
HTTP Request
POST https://backendless.nblocks.cloud/brand/translations
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Body Parameters
Your translations content as JSON. See example
Response
HTTP 200
Get your custom Translations
Request example
TBD
curl --request GET 'https://backendless.nblocks.cloud/brand/translations' \
--header 'x-api-key: YOUR_APP_API_KEY'
Response example:
{
"Login": "Log in",
"Email address": "Email"
}
The translations are used by Nblocks Cloud views, like Nblocks Login and User Management portal.
HTTP Request
GET https://backendless.nblocks.cloud/brand/translations
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Response
HTTP 200
Your translations content as JSON
User authentication
User authentication is done using Nblocks Auth Service that supports Oauth 2.0 / OpenID Connect and tokens are issued as JWTs.
At a glance, the authentication process looks like this:
- You initiate the login process by redirecting the user to the
/authorize
endpoint (or the simpler shorthand/login
and/signup
endpoints). - User is pulled through an authentication process provided by Nblocks with cloud views.
- Once the user is authenticated and has selected the tenant to access the user is redirect back to your app with a code.
- You make a call to the
/token
endpoint with this code to exchange it for access tokens and user profile information (openid). - You can verify that the tokens are valid and safe to trust by using the public keys available from the
/.well-known
endpoint. - You will be able to refresh the tokens using the
/token
endpoint to obtain up to date access and profile information.
Authorize
Start the Oauth 2.0 user login flow by redirecting the user to the /authorize
endpoint. The user will be able to choose login method and after authentication process get back to your app with an auth code that you can exchange for access and openid tokens.
HTTP Request
GET https://auth.nblocks.cloud/authorize
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
client_id | string | Required | Your app id |
response_type | string | Required | What kind of tokens will be generated. We support code |
redirect_uri | string | Required | A target URI where the authenticated user will be redirected to together with tokens. Must be a valid URI in your App redirectUris |
scope | string | Required | Any or all of the following: openid , profile , email , address , phone , onboarding , tenant |
state | string | Optional | This can be used to resume a state in your app. The state will be available in the response code |
force_federation | string | Optional | If you want to force a certain federated login flow instead of letting the user choose during login. Possible values ms-azure-ad and google |
signup | boolean | Optional | If you want to initiate a signup instead of the default login flow for the user. |
Get tokens
Request example exchanging code for tokens
const response = await client.auth.getTokens({code: "XXXX"});
curl --request POST 'https://auth.nblocks.cloud/token' \
--data-raw '{
client_id: "YOUR_APP_ID", grant_type: "authorization_code", code: "XXXX", "redirect_uri": "http://localhost:8080/auth/oauth-callback"
}'
Request example exchanging refresh token for tokens
const response = await client.auth.refreshTokens({refreshToken: "XXXX"});
curl --request POST 'https://auth.nblocks.cloud/token' \
--data-raw '{
client_id: "YOUR_APP_ID", grant_type: "refresh_token", refresh_token: "XXXX"
}'
Response example:
{
"access_token": "XXXX",
"refresh_token": "XXXX",
"token_type": "Bearer",
"expires_in": "XXXX",
"id_token": "XXXX"
}
Get new tokens using an authorization code from a user just completed authentication or by using the refresh token that was issued to a logged in user before. This endpoints serves both cases.
HTTP Request
POST https://auth.nblocks.cloud/token
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
client_id | string | Required | Your app id |
grant_type | string | Required | authorization_code or refresh_token |
code | string | Required for authorization_code |
The code you recieved from the authenticated user. |
redirect_uri | string | Required for authorization_code |
A target URI where the authenticated user will be redirected to together with tokens. Must be a valid URI in your App redirectUris |
refresh_token | string | Required for refresh_token |
The refresh token that was issued when getting the tokens before |
Response
HTTP 200
Short hand authorize
Shorthand endpoints exists so you can use them with less parameters using sensible defaults. Use the simpler short hand endpoint /url/login
to initiate the login flow. The Nblocks will collect your default config and issue the Oauth 2.0 flow.
HTTP Request
GET https://auth.nblocks.cloud/url/login/:YOUR_APP_ID
URL Parameters
Parameter | Description |
---|---|
YOUR_APP_ID | The ID of your app |
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
redirectUri | string | Optional | A target URI where the authenticated user will be redirected to together with tokens. The default value is your App defaultCallbackUri . |
state | string | Optional | This can be used to resume a state in your app. The state will be available in the response code |
forceFederation | string | Optional | If you want to force a certain federated login flow instead of letting the user choose during login. We support ms-azure-ad |
Short hand signup
Shorthand endpoints exists so you can use them with less parameters using sensible defaults. Use the simpler short hand endpoint /url/signup
to initiate the signup flow. The Nblocks will collect your default config and issue the Oauth 2.0 flow.
HTTP Request
GET https://auth.nblocks.cloud/url/signup/:YOUR_APP_ID
URL Parameters
Parameter | Description |
---|---|
YOUR_APP_ID | The ID of your app |
Query Parameters
Parameter | Type | Required | Description |
---|---|---|---|
redirectUri | string | Optional | A target URI where the authenticated user will be redirected to together with tokens. The default value is your App defaultCallbackUri . |
state | string | Optional | This can be used to resume a state in your app. The state will be available in the response code |
forceFederation | string | Optional | If you want to force a certain federated login flow instead of letting the user choose during login. We support ms-azure-ad |
Shorthand get tokens
Request example exchanging code for tokens
const response = await client.auth.getTokens({code: "XXXX"});
curl --request POST 'https://auth.nblocks.cloud/token/code/YOUR_APP_ID' \
--data-raw '{
"code": "XXXX"
}'
Request example exchanging refresh token for tokens
const response = await client.auth.refreshTokens({refreshToken: "XXXX"});
curl --request POST 'https://auth.nblocks.cloud/token/refresh/YOUR_APP_ID' \
--data-raw '{
"refreshToken": "XXXX"
}'
Response example:
{
"access_token": "XXXX",
"refresh_token": "XXXX",
"token_type": "Bearer",
"expires_in": "XXXX",
"id_token": "XXXX",
"user_profile": {
"sub": "63d25a9e0796d40008680f9a",
"name": "John Doe",
"family_name": "Doe",
"given_name": "John",
"preferred_username": "john@example.com",
"locale": "en",
"email": "john@example.com",
"email_verified": true,
"onboarded": true,
"tenant_id": "63d25a9e0796d40008680f96",
"tenant_name": "Johns Family",
"tenant_locale": "en",
"tenant_logo": "",
}
}
Shorthand endpoints exists so you can use them with less parameters using sensible defaults. Get new tokens using an authorization code from a user just completed authentication or by using the refresh token that was issued to a logged in user before. This endpoints serves both cases.
HTTP Request
POST https://auth.nblocks.cloud/token/:grantType/:YOUR_APP_ID
URL Parameters
Parameter | Description |
---|---|
grantType | code or refresh |
YOUR_APP_ID | The ID of your app |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
code | string | Required for code grant | The code you recieved from the authenticated user. |
refreshToken | string | Required for refresh grant | The refresh token that was issued when getting the tokens before |
redirectUri | string | Optional for code grant | A target URI where the authenticated user will be redirected to together with tokens. The default value is your App defaultCallbackUri . |
Response
HTTP 200
Handover code
Request example getting handover code
TBD
curl --request POST 'https://auth.nblocks.cloud/handover/code/YOUR_APP_ID' \
--data-raw '{
"accessToken": "XXXX"
}'
Response example:
{
"code": "XXXX"
}
This endpoint returns a handover code which is used when redirecting to or displaying Nblocks hosted views and user interactions. The code is shortlived and should be consumed with a follow up call to which interaction you want to display for the user.
HTTP Request
POST https://auth.nblocks.cloud/handover/code/:YOUR_APP_ID
URL Parameters
Parameter | Description |
---|---|
YOUR_APP_ID | The ID of your app |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
accessToken | string | Yes | A valid user access token |
Response
HTTP 200
Parameter | Type | Description |
---|---|---|
code | string | A shortlived unique token |
Users
These are your app's users. We call them Tenant users since, they belong to a tenant. But they can use the same credentials to access multiple tenants should their username exists in several places.
User management portal - Users
This endpoint renders Nblocks hosted user management views for listing and managing users. Redirect the user agent or embedd this url into an iframe to render the view. Users will be able to list and invite other users to the same tenant. See Handover code for how to obtain the code parameter required for this call.
HTTP Request
GET https://backendless.nblocks.cloud/user-management-portal/users?code=XXXX
URL Parameters
Parameter | Description |
---|---|
code | The code recieved from handover endpoint |
Tenants
A tenant represents a customers workspace in your app. These are isolated data silos of team members, settings, and application data.
List all tenants
Request example
const response = await client.tenants.list();
curl --request GET 'https://account-api.nebulr-core.com/tenant' \
--header 'x-api-key: YOUR_APP_API_KEY'
Response example:
[
{
"id": "606b00a61679e20008a5654d",
"plan": "TEAM",
"mfa": false,
"locale": "en",
"name": "John Inc",
"logo": "",
"metadata": {},
"createdAt": "2021-04-05T12:20:54.890Z",
"paymentsEnabled": false,
"paymentsRequired": true,
"onboarded": true
},
{
"id": "605dd819e8fd3e00086cc552",
"plan": "ESSENTIAL",
"mfa": false,
"locale": "en",
"name": "Dave Ltd",
"logo": "",
"metadata": {},
"createdAt": "2021-03-26T12:48:25.187Z",
"paymentsEnabled": false,
"paymentsRequired": true,
"onboarded": true
}
]
Lists all tenants in your app. Each tenant will have their own sets of users.
HTTP Request
GET https://account-api.nebulr-core.com/tenant
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Response
HTTP 200
A list of Tenant models
Get tenant by id
Request example
const response = await client.tenant('606b00a61679e20008a5654d').get();
curl --request GET 'https://account-api.nebulr-core.com/tenant/byId/606b00a61679e20008a5654d' \
--header 'x-api-key: YOUR_APP_API_KEY'
Response example:
{
"id": "606b00a61679e20008a5654d",
"plan": "TEAM",
"mfa": false,
"locale": "en",
"name": "John Inc",
"logo": "",
"metadata": {},
"createdAt": "2021-04-05T12:20:54.890Z",
"paymentsEnabled": false,
"paymentsRequired": true,
"onboarded": true
}
Get a single tenant in your app
HTTP Request
GET https://account-api.nebulr-core.com/tenant/byId/:TENANT_ID
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
URL Parameters
Parameter | Description |
---|---|
TENANT_ID | The ID of the tenant |
Response
HTTP 200
Create new tenant
Request example
const response = await client.tenants.create(
{
name: "New Company Ltd",
plan: "TEAM",
owner: {
email: "john@example.com",
firstName: "John",
lastName: "Doe"
},
metadata: {
VIP: "true"
}
});
curl --request POST 'https://account-api.nebulr-core.com/tenant' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"name": "New Company Ltd","plan": "TEAM", "owner": {"email": "john@example.com", "firstName": "John", "lastName": "Doe"},"metadata": {"VIP": "true"}
}'
Response example:
{
"id": "606b00a61679e20008a5654d",
"plan": "TEAM",
"mfa": false,
"locale": "en",
"name": "John Inc",
"logo": "",
"metadata": {},
"createdAt": "2021-04-05T12:20:54.890Z",
"paymentsEnabled": false,
"paymentsRequired": true,
"onboarded": true
}
Creates a new tenant with an initial user that is regarded as the tenant owner.
HTTP Request
POST https://account-api.nebulr-core.com/tenant
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
owner | TenantOwner | Required | A user will need to be assigned as an owner to this tenant. Either reused if the user already exist or a new user will be created. The user will be onboarded automatically. See below |
name | string | Optional | Name of the tenant. Can also be set by tenant owner during onboarding |
plan | string | Optional | The plan must be present in the configured App business model |
logo | string | Optional | A URI to a logo. Can also be set by tenant owner during onboarding |
metadata | Record |
Optional | Store metadata for your own business logic that will be returned in every Tenant response. This data will never be outputted to the end user |
TenantOwner
Parameter | Type | Required | Description |
---|---|---|---|
string | Required | A user will need to be assigned as an owner to this tenant. Either reused if the user already exist or a new user will be created. The user will be onboarded automatically | |
firstName | string | Optional | The first name. Can also be set by tenant owner during onboarding |
lastName | string | Optional | The last name. Can also be set by tenant owner during onboarding |
muteNotifications | boolean | Optional | Set this variable to true if you don't wish to send out any invitation/notifications to the new user |
Response
HTTP 201
Update tenant
Request example
const response = await client.tenant('606b00a61679e20008a5654d').update(
{
logo: "http://path/to/logo.png",
locale: "en"
});
curl --request PUT 'https://account-api.nebulr-core.com/tenant/606b00a61679e20008a5654d' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"logo": "http://path/to/logo.png","locale": "en"
}'
Response example:
{
"id": "606b00a61679e20008a5654d",
"plan": "TEAM",
"mfa": false,
"locale": "en",
"name": "John Inc",
"logo": "",
"metadata": {},
"createdAt": "2021-04-05T12:20:54.890Z",
"paymentsEnabled": false,
"paymentsRequired": true,
"onboarded": true
}
Update an existing tenant.
HTTP Request
PUT https://account-api.nebulr-core.com/tenant/TENANT_ID
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Optional | Name of the tenant. |
locale | string | Optional | The default locale / lang code for all users in this tenant (ISO_639-1 format). This property will set the i18n for all platform emails |
plan | string | Optional | The plan must be present in the configured App business model |
logo | string | Optional | A URI to a logo. |
mfa | boolean | Optional | Require users to login with MFA/2FA |
metadata | Record |
Optional | Store metadata for your own business logic that will be returned in every Tenant response. This data will never be outputted to the end user |
Response
HTTP 200
Feature flags
Feature flags allows you to conditionally give access to or show / hide features or content to your users.
To use feature flags you must first create Flags and link them with Segments. Then you can start making Evaluation calls where you provide the current Context and the API will take care of matching the context with the segments and returns if the flag is enabled or not.
Some use cases for feature flags are:
- Restrict access to premium content that just users with a certain plan can access
- Try beta features on a selection of customers
- Show a message to all users during a scheduled release.
Evaluate a flag
Request example
TBD
curl --request POST 'https://backendless.nblocks.cloud/flags/evaluate/605b603cfeb49f00082686b6/iphone-feature' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"context": {
"device": {
"key": "iphone"
},
"user": {
"key": "fooBar"
}
},
"accessToken": "XXXX"
}'
Response example:
{
"enabled": true
}
Evaluate a single flag by providing context or user access token.
You can send whatever context information you want to the evaluation api. But we've simplified it using a base structure so you can build the segment targets in Nblocks Admin more easily.
The context object contains three areas, user
, org
and device
.
Each one of them contains the property key
. You can assign any value to this property.
You can also assign any values you want to the other properties.
When building the segment targets you can define is the value should be equal (==
), contain, beginWith or endWith the value.
Structure of the body that can be sent to /flags/evaluate
Providing the access token will automatically resolve all values for user and org so you don't have to.
HTTP Request
POST https://backendless.nblocks.cloud/flags/evaluate/APP_ID/FLAG_KEY
URL Parameters
Parameter | Description |
---|---|
APP_ID | Your app id |
FLAG_ID | The ID of the flag |
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
context | Context | No | A context object |
accessToken | string | No | A user token |
Response
HTTP 200
Parameter | Type | Description |
---|---|---|
enabled | boolean | Evaluation result. If the flag is enabled or not. Use this to conditionally render the feature |
Evaluate flags in bulk
Request example
TBD
curl --request POST 'https://backendless.nblocks.cloud/flags/bulkEvaluate/605b603cfeb49f00082686b6' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"context": {
"device": {
"key": "iphone"
},
"user": {
"key": "fooBar"
}
},
"accessToken": "XXXX"
}'
Response example:
{
"flags": [
{
"flag": "iphone-feature",
"evaluation": {
"enabled": true
}
}
]
}
Evaluate all flags in bulk by providing context or user access token. Use this to limit the amount of individual flag evaluation calls
You can send whatever context information you want to the evaluation api. But we've simplified it using a base structure so you can build the segment targets in Nblocks Admin more easily.
The context object contains three areas, user
, org
and device
.
Each one of them contains the property key
. You can assign any value to this property.
You can also assign any values you want to the other properties.
When building the segment targets you can define is the value should be equal (==
), contain, beginWith or endWith the value.
Structure of the body that can be sent to /flags/evaluate
Providing the access token will automatically resolve all values for user and org so you don't have to.
HTTP Request
POST https://backendless.nblocks.cloud/flags/bulkEvaluate/APP_ID
URL Parameters
Parameter | Description |
---|---|
APP_ID | Your app id |
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
context | Context | No | A context object |
accessToken | string | No | A user token |
Response
HTTP 200
Parameter | Type | Description |
---|---|---|
flags | EvaluatedFlag[] | Individual evaluation response for each flag |
EvaluatedFlag
Parameter | Type | Description |
---|---|---|
flag | string | Flag key |
evaluation | EvaluationResponse | The evaluation response |
EvaluationResponse
Parameter | Type | Description |
---|---|---|
enabled | boolean | If the flag is enabled or not. Use this to conditionally render the feature |
List segments
Request example
TBD
curl --request GET 'https://admin-api.nblocks.cloud/flags/segment' \
--header 'x-api-key: YOUR_APP_API_KEY'
Response example:
[
{
"id": "64c63e7adaf20f0008e71b20",
"key": "iphones",
"description": "This segment targets iPhones",
"targets": [
{
"device": {
"key": {
"operator": "contains",
"value": "iphone"
}
}
}
]
},
{
"id": "64c6400fdaf20f0008e71b25",
"key": "admins",
"description": "This segment targets admins",
"targets": [
{
"user": {
"role": {
"operator": "eq",
"value": "ADMIN"
}
}
}
]
}
]
List all segments
HTTP Request
GET https://admin-api.nblocks.cloud/flags/segment
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Response
HTTP 200
List of Segment
Create a segment
Request example
TBD
curl --request POST 'https://admin-api.nblocks.cloud/flags/segment' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"key": "admins",
"description": "This segment targets admins",
"targets": [
{
"user": {
"role": {
"operator": "eq",
"value": "ADMIN"
}
}
}
]
}'
Response example:
{
"id": "64c6400fdaf20f0008e71b25",
"key": "admins",
"description": "This segment targets admins",
"targets": [
{
"user": {
"role": {
"operator": "eq",
"value": "ADMIN"
}
}
}
]
}
Create a segment
HTTP Request
POST https://admin-api.nblocks.cloud/flags/segment
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
key | string | Yes | A unique key for this segment |
description | string | No | Optional description |
targets | Target[] | No | The targets to match |
Response
HTTP 200
Update a segment
Request example
TBD
curl --request PUT 'https://admin-api.nblocks.cloud/flags/segment/64c6400fdaf20f0008e71b25' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"description": "Updated description",
}'
Response example:
{
"id": "64c6400fdaf20f0008e71b25",
"key": "admins",
"description": "Updated description",
"targets": [
{
"user": {
"role": {
"operator": "eq",
"value": "ADMIN"
}
}
}
]
}
Update an existing segment
HTTP Request
PUT https://admin-api.nblocks.cloud/flags/segment/SEGMENT_ID
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
URL Parameters
Parameter | Description |
---|---|
SEGMENT_ID | The ID of the segment |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
key | string | No | A unique key for this segment |
description | string | No | Optional description |
targets | Target[] | No | The targets to match |
Response
HTTP 200
Delete a segment
Request example
TBD
curl --request DELETE 'https://admin-api.nblocks.cloud/flags/segment/64c6400fdaf20f0008e71b25' \
--header 'x-api-key: YOUR_APP_API_KEY'
Delete an existing segment. Deleting a segment will also remove the relationship with affected flags.
HTTP Request
PUT https://admin-api.nblocks.cloud/flags/segment/SEGMENT_ID
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
URL Parameters
Parameter | Description |
---|---|
SEGMENT_ID | The ID of the segment |
Response
HTTP 200
List flags
Request example
TBD
curl --request GET 'https://admin-api.nblocks.cloud/flags/flags' \
--header 'x-api-key: YOUR_APP_API_KEY'
Response example:
[
{
"id": "64c64cfb47418500082f60b5",
"key": "iphone-feature",
"description": "A feature for iPhones",
"defaultValue": false,
"segments": [
{
"id": "64c63e7adaf20f0008e71b20",
"key": "iphones",
"description": "This segment targets iPhones",
"targets": [
{
"device": {
"key": "iphone"
}
}
]
}
],
"targetValue": true,
"enabled": true
}
]
List all segments
HTTP Request
GET https://admin-api.nblocks.cloud/flags/segment
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Response
HTTP 200
List of Flag
Create a flag
Request example
TBD
curl --request POST 'https://admin-api.nblocks.cloud/flags/flag' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"key": "iphone-feature",
"description": "A feature for iPhones",
"defaultValue": false,
"segments": [
"64c63e7adaf20f0008e71b20"
],
"targetValue": true,
"enabled": true
}'
Response example:
{
"id": "64c64cfb47418500082f60b5",
"key": "iphone-feature",
"description": "A feature for iPhones",
"defaultValue": false,
"segments": [
{
"id": "64c63e7adaf20f0008e71b20",
"key": "iphones",
"description": "This segment targets iPhones",
"targets": [
{
"device": {
"key": "iphone"
}
}
]
}
],
"targetValue": true,
"enabled": true
}
Create a flag
HTTP Request
POST https://admin-api.nblocks.cloud/flags/flag
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
key | string | Yes | A unique key for this flag |
description | string | No | Optional description |
defaultValue | boolean | No | The value to return if no segment was found or matched |
segments | string[] | No | List of IDs of the segments which should be matched |
targetValue | boolean | No | The value to return of a segment was matched |
enabled | boolean | No | Active state. Only enabled flags are available for evaluation. Otherwise evaluation falls back to false. |
Response
HTTP 200
Update a flag
Request example
TBD
curl --request PUT 'https://admin-api.nblocks.cloud/flags/flag/64c6400fdaf20f0008e71b25' \
--header 'x-api-key: YOUR_APP_API_KEY' \
--data-raw '{
"enabled": false,
}'
Response example:
{
"id": "64c64cfb47418500082f60b5",
"key": "iphone-feature",
"description": "A feature for iPhones",
"defaultValue": false,
"segments": [
{
"id": "64c63e7adaf20f0008e71b20",
"key": "iphones",
"description": "This segment targets iPhones",
"targets": [
{
"device": {
"key": "iphone"
}
}
]
}
],
"targetValue": true,
"enabled": false
}
Update an existing flag
HTTP Request
PUT https://admin-api.nblocks.cloud/flags/segment/FLAG_ID
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
URL Parameters
Parameter | Description |
---|---|
FLAG_ID | The ID of the flag |
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
key | string | No | A unique key for this flag |
description | string | No | Optional description |
defaultValue | boolean | No | The value to return if no segment was found or matched |
segments | string[] | No | List of IDs of the segments which should be matched |
targetValue | boolean | No | The value to return of a segment was matched |
enabled | boolean | No | Active state. Only enabled flags are available for evaluation. Otherwise evaluation falls back to false. |
Response
HTTP 200
Delete a flag
Request example
TBD
curl --request DELETE 'https://admin-api.nblocks.cloud/flags/flag/64c6400fdaf20f0008e71b25' \
--header 'x-api-key: YOUR_APP_API_KEY'
Delete an existing flag.
HTTP Request
PUT https://admin-api.nblocks.cloud/flags/flag/FLAG_ID
Headers
Parameter | Type | Required | Description |
---|---|---|---|
x-api-key | string | Required | Your app api key |
URL Parameters
Parameter | Description |
---|---|
FLAG_ID | The ID of the flag |
Response
HTTP 200
Import data
Import data into your Nblocks app using these endpoints.
Import tenants
Request example:
[
{
"tenant":{
"name":"John Ltd",
"plan":"MEDIUM",
"owner":{
"username":"peter@doe.com",
"firstName":"Peter",
"lastName":"Doe"
}
},
"users":[
{
"username":"john@doe.com",
"firstName":"John",
"lastName":"Doe",
"role":"ADMIN"
},
{
"username":"lisa@doe.com",
"firstName":"Lisa",
"lastName":"Doe",
"role":"ADMIN",
"password": {
"value": "$2a$10$f8zztJfuSgYc0Z8SGA3jb./KB5a2GY8lmwa9bgbRv/P0.1XNBhovy",
"algorithm": "BCRYPT",
"pepper": {
"value": "foobar",
"position": "END"
}
}
}
]
},
{
"tenant":{
"name":"",
"plan":"",
"owner":{
"username":"foo@bar.com",
"firstName":"Peter",
"lastName":"Doe"
}
},
"users":[]
}
]
Response example:
{
"status": "SCHEDULED",
"reference": "606b00a61679e20008d5654b",
"import": {
"tenants": 2,
"users": 4,
"passwords": false,
"errors": [],
"warnings": [],
"approved": true
}
}
This endpoint allows you to import tenants and their users. No notification emails wil be sent to the imported users. The import is asynchronous so it will be scheduled immediately and then completed once every tenant and user has been imported. A notification will be sent to your email when the import has completed. Before you make the request, you can validate your input and check for errors or warnings.
How will the imported users authenticate?
The import supports importing new users both with or without existing passwords.
New users imported without a password can authenticated using the configured SSO option. Then will be asked to reset their password should they try to login with username.
When importing passwords Nblocks will use the imported password to authenticate the user once. Thereafter a new password digest is generated this will be used in all future authentications.
HTTP Request
POST https://account-api.nebulr-core.com/import/tenants
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
tenant | ImportTenant | Required | Import data for the tenant |
users | ImportUser[] | Optional | All other users than the owner that should be imported to this tenant |
ImportTenant
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Optional | Name of the tenant. |
owner | ImportUser | Required | The owner for this tenant. There must be one owner |
plan | string | Optional | The plan must be present in the configured App business model |
logo | string | Optional | A URI to a logo. |
metadata | Record |
Optional | Store metadata for your own business logic that will be returned in every Tenant response. This data will never be outputted to the end user |
ImportUser
Parameter | Type | Required | Description |
---|---|---|---|
username | string | Required | The username / email. |
role | string | Optional | Role of the user |
firstName | string | Optional | Users first name |
lastName | string | Optional | Users last name |
password | ImportPassword | Optional | Import an existing password |
ImportPassword
Parameter | Type | Required | Description |
---|---|---|---|
value | string | Required | The password digest. |
algorithm | string | Required | The algorithm that is being used. Possible values: BCRYPT , ARGON2I , MD5 , SHA1 , SHA256 or SHA512 . |
pepper | ImportPasswordPepper | Optional | If the password should be peppered prior to validation. Read more. |
ImportPasswordPepper
Parameter | Type | Required | Description |
---|---|---|---|
value | string | Required | The pepper value. |
position | string | Required | If the pepper should be prepended or appended the password. Possible values: BEGIN or END . |
Response
HTTP 200
Validate import tenants data
[
{
"tenant":{
"name":"John Ltd",
"plan":"MEDIUM",
"owner":{
"username":"peter@doe.com",
"firstName":"Peter",
"lastName":"Doe"
}
},
"users":[
{
"username":"john@doe.com",
"firstName":"John",
"lastName":"Doe",
"role":"ADMIN"
},
{
"username":"lisa@doe.com",
"firstName":"Lisa",
"lastName":"Doe",
"role":"ADMIN",
"password": {
"value": "$2a$10$f8zztJfuSgYc0Z8SGA3jb./KB5a2GY8lmwa9bgbRv/P0.1XNBhovy",
"algorithm": "BCRYPT",
"pepper": {
"value": "foobar",
"position": "END"
}
}
}
]
},
{
"tenant":{
"name":"",
"plan":"",
"owner":{
"username":"foo@bar.com",
"firstName":"Peter",
"lastName":"Doe"
}
},
"users":[]
}
]
Response example:
{
"tenants": 2,
"users": 4,
"passwords": false,
"errors": [
"One or more users are missing an username"
],
"warnings": [],
"approved": false
}
Validates the import body and returns a result that summarizes the import and if there are any errors or warnings.
HTTP Request
POST https://account-api.nebulr-core.com/import/validateTenants
Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
tenant | ImportTenant | Required | Import data for the tenant |
users | ImportUser[] | Optional | All other users than the owner that should be imported to this tenant |
ImportTenant
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Optional | Name of the tenant. |
owner | ImportUser | Required | The owner for this tenant. There must be one owner |
plan | string | Optional | The plan must be present in the configured App business model |
logo | string | Optional | A URI to a logo. |
metadata | Record |
Optional | Store metadata for your own business logic that will be returned in every Tenant response. This data will never be outputted to the end user |
ImportUser
Parameter | Type | Required | Description |
---|---|---|---|
username | string | Required | The username / email. |
role | string | Optional | Role of the user |
firstName | string | Optional | Users first name |
lastName | string | Optional | Users last name |
password | ImportPassword | Optional | Import an existing password |
ImportPassword
Parameter | Type | Required | Description |
---|---|---|---|
value | string | Required | The password digest. |
algorithm | string | Required | The algorithm that is being used. Possible values: BCRYPT , ARGON2I , MD5 , SHA1 , SHA256 or SHA512 . |
pepper | ImportPasswordPepper | Optional | If the password should be peppered prior to validation. Read more. |
ImportPasswordPepper
Parameter | Type | Required | Description |
---|---|---|---|
value | string | Required | The pepper value. |
position | string | Required | If the pepper should be prepended or appended the password. Possible values: BEGIN or END . |
Webhook
These events are sent to your webhook endpoint. See Update app profile how to configure a webhook
Tenant created event
Request example:
{
"events": [
{
"type": "TENANT_CREATED",
"timestamp": "2023-08-11T08:10:28.240Z",
"data": {
"id": "63cad6ac48dcba47e9322848",
"mfa": false,
"locale": "en",
"name": "John's place",
"logo": "",
"metadata": {},
"createdAt": "2023-01-20T18:00:12.393Z",
"paymentsEnabled": false,
"paymentsRequired": false,
"onboarded": true
}
}
]
}
Parameter | Type | Description |
---|---|---|
type | string | Event type |
timestamp | string | When the event occurred |
data | Tenant | Event body |
Tenant updated event
Request example:
{
"events": [
{
"type": "TENANT_UPDATED",
"timestamp": "2023-08-11T08:10:28.240Z",
"data": {
"id": "63cad6ac48dcba47e9322848",
"mfa": false,
"locale": "en",
"name": "John's place",
"logo": "",
"metadata": {},
"createdAt": "2023-01-20T18:00:12.393Z",
"paymentsEnabled": false,
"paymentsRequired": false,
"onboarded": true
}
}
]
}
Parameter | Type | Description |
---|---|---|
type | string | Event type |
timestamp | string | When the event occurred |
data | Tenant | Event body |
Tenant user created event
Request example:
{
"events": [
{
"type": "TENANT_USER_CREATED",
"timestamp": "2023-08-11T08:29:22.469Z",
"data": {
"id": "63cad6ac48dcba47e9322853",
"role": "OWNER",
"email": "john.doe@example.com",
"username": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"onboarded": true,
"consentsToPrivacyPolicy": false,
"enabled": true,
"teams": [
"cool_gang"
],
"createdAt": "2023-01-20T18:00:12.489Z",
"tenant": {
"id": "63cad6ac48dcba47e9322848",
"mfa": false,
"locale": "en",
"name": "John's place",
"logo": "",
"metadata": {},
"createdAt": "2023-01-20T18:00:12.393Z",
"paymentsEnabled": false,
"paymentsRequired": false,
"onboarded": true
}
}
}
]
}
Parameter | Type | Description |
---|---|---|
type | string | Event type |
timestamp | string | When the event occurred |
data | Tenant user | Event body |
Tenant user updated event
Request example:
{
"events": [
{
"type": "TENANT_USER_UPDATED",
"timestamp": "2023-08-11T08:29:22.469Z",
"data": {
"id": "63cad6ac48dcba47e9322853",
"role": "OWNER",
"email": "john.doe@example.com",
"username": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"onboarded": true,
"consentsToPrivacyPolicy": false,
"enabled": true,
"teams": [
"cool_gang"
],
"createdAt": "2023-01-20T18:00:12.489Z",
"tenant": {
"id": "63cad6ac48dcba47e9322848",
"mfa": false,
"locale": "en",
"name": "John's place",
"logo": "",
"metadata": {},
"createdAt": "2023-01-20T18:00:12.393Z",
"paymentsEnabled": false,
"paymentsRequired": false,
"onboarded": true
}
}
}
]
}
Parameter | Type | Description |
---|---|---|
type | string | Event type |
timestamp | string | When the event occurred |
data | Tenant user | Event body |
Tenant user deleted event
Request example:
{
"events": [
{
"type": "TENANT_USER_DELETED",
"timestamp": "2023-08-11T08:29:22.469Z",
"data": {
"id": "63cad6ac48dcba47e9322853",
"role": "OWNER",
"email": "john.doe@example.com",
"username": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"onboarded": true,
"consentsToPrivacyPolicy": false,
"enabled": true,
"teams": [
"cool_gang"
],
"createdAt": "2023-01-20T18:00:12.489Z",
"tenant": {
"id": "63cad6ac48dcba47e9322848",
"mfa": false,
"locale": "en",
"name": "John's place",
"logo": "",
"metadata": {},
"createdAt": "2023-01-20T18:00:12.393Z",
"paymentsEnabled": false,
"paymentsRequired": false,
"onboarded": true
}
}
}
]
}
Parameter | Type | Description |
---|---|---|
type | string | Event type |
timestamp | string | When the event occurred |
data | Tenant user | Event body |
Models
App profile model
Model example:
{
"id": "624c14cc0c01e70033356282",
"name": "My app",
"domain": "MY_APP",
"apiUrl": "http://localhost:3000",
"uiUrl": "http://localhost:8100",
"webhookUrl": "http://api.example.com/webhook"
"stripeEnabled": false,
"passkeysEnabled": true,
"azureMarketplaceEnabled": false,
"googleSsoEnabled": false,
"azureAdSsoEnabled": true,
"onboardingFlow": "B2B",
"cloudViews": true,
"redirectUris": ["http://localhost:8080/auth/oauth-callback"],
"defaultCallbackUri": "http://localhost:8080/auth/oauth-callback",
"defaultRole": "OWNER",
"roles": {
"OWNER": [
"AUTHENTICATED",
"TENANT_READ",
"TENANT_WRITE",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"TAG_WRITE",
"USER_READ",
"USER_WRITE",
"GROUP_WRITE",
"GROUP_READ",
"ASSIGNEES_WRITE",
"SETTINGS_READ",
"SETTINGS_WRITE"
],
"ADMIN": [
"AUTHENTICATED",
"TENANT_READ",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"TAG_WRITE",
"USER_READ",
"USER_WRITE",
"GROUP_WRITE",
"GROUP_READ",
"ASSIGNEES_WRITE",
"SETTINGS_READ",
"SETTINGS_WRITE"
],
"MANAGER": [
"AUTHENTICATED",
"TENANT_READ",
"CASE_READ",
"CASE_WRITE",
"TAG_READ",
"USER_READ",
"GROUP_READ",
"SETTINGS_READ"
],
},
"businessModel": {
"taxes": [
{
"region": "SE",
"name": "VAT",
"percentage": 25
}
],
"plans": [
{
"name": "ESSENTIAL",
"prices": [
{
"region": "SE",
"amount": 500,
"currency": "SEK",
"recurrenceInterval": "month"
},
{
"region": "DE",
"amount": 50,
"currency": "EUR",
"recurrenceInterval": "month"
}
]
},
{
"name": "TEAM",
"trialDays": 14,
"prices": [
{
"region": "SE",
"amount": 1000,
"currency": "SEK",
"recurrenceInterval": "month"
},
{
"region": "DE",
"amount": 100,
"currency": "EUR",
"recurrenceInterval": "month"
}
]
}
]
},
"logo": "https://public.nblocks.dev/assets/logos/nblocks-logo-black.svg",
"websiteUrl": "http://localhost",
"privacyPolicyUrl": "",
"termsOfServiceUrl": ""
}
Parameter | Type | Description |
---|---|---|
id | string | Unique ID (Read only) |
name | string | Name of the app |
domain | string | Unique domain name of the app (Read only) |
apiUrl | string | URL to your api (to receive webhooks etc). |
webhookUrl | string | Enable webhook and events to be sent to this url |
defaultRole | string | Default user role |
uiUrl | string | URL to your frontend app (for onboarding redirects etc). |
roles | Record |
All user roles and their granted privileges |
businessModel | BusinessModel | The business model defines what plans are available to subscribe to and what taxes applies. |
logo | string | URL to your logo |
websiteUrl | string | URL to your website or landing page. E.g. Branded emails will link to this URL, checkout process will redirect to /payment-success and /payment-cancel |
privacyPolicyUrl | string | URL to a page on your website containing a Privacy policy for your app users. E.g. checkout process will link to this url. |
termsOfServiceUrl | string | URL to a page on your website containing a Terms of service for your app users. E.g. checkout process will link to this url. |
emailSenderName | string | Emails sent from Nblocks will have this sender name |
emailSenderEmail | string | Emails sent from Nblocks will have this sender email. You'll have to verify this email before |
stripeEnabled | boolean | Boolean value telling the user if Stripe is enabled (Read only) |
passkeysEnabled | boolean | Boolean value telling the user if Login with Passkeys is enabled |
azureMarketplaceEnabled | boolean | Boolean value telling the user if Azure marketplace is enabled (Read only) |
googleSsoEnabled | boolean | Boolean value telling the user if Login with Google SSO is enabled (Read only) |
azureAdSsoEnabled | boolean | Boolean value telling the user if Login with Azure SSO is enabled (Read only) |
onboardingFlow | OnboardingFlow | Configure how users will be onboarded |
cloudViews | boolean | Toggle this to true if you want to use a UI provided by NBlocks instead of your own |
redirectUris | string[] | Allowed redirect uris |
defaultCallbackUri | string | Default handover/callback uri used by Nblocks |
Business model
Model example:
{
"taxes": [
{
"region": "SE",
"name": "VAT",
"percentage": 25
}
],
"plans": [
{
"name": "ESSENTIAL",
"prices": [
{
"region": "SE",
"amount": 500,
"currency": "SEK",
"recurrenceInterval": "month"
},
{
"region": "DE",
"amount": 50,
"currency": "EUR",
"recurrenceInterval": "month"
}
]
},
{
"name": "TEAM",
"trialDays": 14,
"prices": [
{
"region": "SE",
"amount": 1000,
"currency": "SEK",
"recurrenceInterval": "month"
},
{
"region": "DE",
"amount": 100,
"currency": "EUR",
"recurrenceInterval": "month"
}
]
}
]
}
Parameter | Type | Description |
---|---|---|
taxes | Tax[] | A list of Taxes for different countries |
plans | Plan[] | A list of Plans which your customers can subscribe to |
Tenant model
{
"id": "624c14cc0c01e70033356285",
"plan": "TEAM",
"mfa": false,
"paymentsEnabled": false,
"paymentsRequired": false,
"locale": "en",
"name": "Nebulr AB",
"logo": "https://nebulr-group.github.io/nblocks-docs/img/logo.png",
"metadata": {},
"onboarded": true,
"createdAt": "2022-04-05T10:07:08.235Z"
}
Parameter | Type | Description |
---|---|---|
id | string | Unique ID (Read only) |
plan | string | Name of the subscription plan. Automatically set by the payment service if tenant used the checkout process |
locale | string | The default locale / lang code for all users in this tenant (ISO_639-1 format). This property will set the i18n for all platform emails |
name | string | Name of the tenant |
logo | string | URI to a logo |
mfa | boolean | Require users to login with MFA/2FA |
paymentsEnabled | boolean | The tenant has been setup with a payment solution |
paymentsRequired | boolean | The tenant should setup payment immediately because tenant has not setup payments and the subscribing plan carry a cost or the trial has ended |
metadata | Record |
Custom key value meta data that you can use |
onboarded | string | If this tenant is considered onboarded (Read only) |
createdAt | string | Timestamp when created (Read only) |
Tenant user model
{
"id": "63cad6ac48dcba47e9322853",
"role": "OWNER",
"email": "john.doe@example.com",
"username": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"onboarded": true,
"consentsToPrivacyPolicy": false,
"enabled": true,
"teams": [
"cool_gang"
],
"createdAt": "2023-01-20T18:00:12.489Z",
"tenant": {
"id": "63cad6ac48dcba47e9322848",
"mfa": false,
"locale": "en",
"name": "John's place",
"logo": "",
"metadata": {},
"createdAt": "2023-01-20T18:00:12.393Z",
"paymentsEnabled": false,
"paymentsRequired": false,
"onboarded": true
}
}
Parameter | Type | Description |
---|---|---|
id | string | Unique ID (Read only) |
role | string | Role of the user. Grants a set of privileges. Privileges are configured on the App model. |
string | Email address | |
username | string | Username |
firstName | string | Users first name |
lastName | string | Users last name |
fullName | string | Users full name (first name and last name concatenated) |
onboarded | boolean | If user is onboarded or not |
consentsToPrivacyPolicy | boolean | If user have left consent to the app privacy policy or not (should be set during app onboarding) |
enabled | boolean | If user should be allowed to login or not |
teams | string[] | Array of identifiers that can be used to group several users into teams or groups |
createdAt | string | Timestamp when created (Read only) |
tenant | Tenant | The tenant |
Tokens response
Parameter | Type | Description |
---|---|---|
token_type | string | Token type |
expires_in | number | Seconds before the access_token expires |
access_token | string | (JWT) The access token containing authentication and access control data only) |
refresh_token | string | (JWT) The token use for refreshing the access token before it expires app |
id_token | string | (JWT) The OpenId Connect user profile id |
user_profile | object | A decoded id_token JWT as JSON. Available in Shorthand get tokens endpoint |
Access token model
{
"sub": "63d25a9e0796d40008680f9a",
"scope": "TENANT_WRITE TENANT_READ USER_WRITE USER_READ AUTHENTICATED",
"role": "OWNER",
"aid": "624c14cc0c01e70033356282",
"tid": "63d25a9e0796d40008680f96",
"plan": "Basic"
}
Decoded JWT payload.
Parameter | Type | Description |
---|---|---|
sub | string | User id |
scope | string | User privileges |
role | string | User role |
aid | string | Your app id |
tid | string | User tenant id |
plan | string | User tenant plan |
Id token model
{
"sub": "63d25a9e0796d40008680f9a"
"name": "John Doe",
"family_name": "Doe",
"given_name": "John",
"preferred_username": "john@example.com",
"locale": "en",
"email": "john@example.com",
"email_verified": true,
"onboarded": true,
"tenant_id": "63d25a9e0796d40008680f96",
"tenant_name": "Johns Family",
"tenant_locale": "en",
"tenant_logo": "",
}
Decoded JWT payload.
Parameter | Type | Description |
---|---|---|
sub | string | User id |
name | string | Users full name |
family_name | string | Users last name |
given_name | string | Users first name |
preferred_username | string | Username |
locale | string | Users preferred locale |
string | User email | |
email_verified | boolean | The users email address has been verified |
onboarded | boolean | Have the user completed onboarding or not |
tenant_id | string | Tenant id |
tenant_name | string | Tenant name |
tenant_locale | string | The preferred locale of the whole tenant |
tenant_logo | string | Tenant logo URI |
Import tenant response
Model example:
{
"status": "SCHEDULED",
"import": {
"tenants": 2,
"users": 4,
"passwords": false,
"errors": [],
"warnings": [],
"approved": true
}
}
Parameter | Type | Description |
---|---|---|
status | string | User context |
import | Validate response | A summary of the import and if there are any errors |
Validate import tenant response
Model example:
{
"tenants": 2,
"users": 4,
"passwords": false,
"errors": [
"One or more users are missing an username"
],
"warnings": [],
"approved": false
}
Parameter | Type | Description |
---|---|---|
tenants | number | The total numbers of tenants that will be imported |
users | number | The total numbers of users (across all tenants) that will be imported |
passwords | boolean | If there will be any user credentials migrated during the import |
errors | string[] | A list of errors. These errors are blocking the import |
warnings | string[] | A list of warnings. These warnings are not blocking the import |
approved | boolean | If the data will or was approved for import |
Feature flags evaluation context
Model example:
{
"user": {
"key": "foobar",
"id": "63d2ab029e23db0afb07a5a7",
"role": "ADMIN",
"name": "John Doe";
}
"org": {
"key": "helloworld",
"id": "63d2ab029e23db0afb07a5a7",
"plan": "PREMIUM",
"name": "My Workspace"
}
"device": {
"key": "iphone"
}
}
Parameter | Type | Description |
---|---|---|
user | UserContext | User context |
org | OrgContext | Org context |
device | KeyContext | Device context |
UserContext
Parameter | Type | Description |
---|---|---|
key | string | Custom value |
id | string | User id |
role | string | User role |
name | string | User name |
OrgContext
Parameter | Type | Description |
---|---|---|
key | string | Custom value |
id | string | Tenant id |
plan | string | Tenant plan |
name | string | Tenant name |
KeyContext
Parameter | Type | Description |
---|---|---|
key | string | The value to be matched (==) |
Feature flags segment
Model example:
{
"id": "64c6400fdaf20f0008e71b25",
"key": "admins",
"description": "This segment targets admins",
"targets": [
{
"user": {
"role": {
"operator": "eq",
"value": "ADMIN"
}
}
}
]
}
Parameter | Type | Description |
---|---|---|
id | string | Unique ID (Read only) |
key | string | Segment key. Use this to reference the segment in a flag |
description | string | Description text |
targets | Target[] | The target which will be used to match |
Feature flags segment target
Model example:
{
"device": {
"key": {
"operator": "contains",
"value": "iphone"
}
}
}
Parameter | Type | Description |
---|---|---|
user | UserTarget | User id |
org | OrgTarget | Users full name |
device | KeyTarget | Users last name |
UserTarget
Parameter | Type | Description |
---|---|---|
key | TargetValue | Custom value |
id | string | User id |
role | TargetValue | User role |
name | TargetValue | User name |
OrgTarget
Parameter | Type | Description |
---|---|---|
key | TargetValue | Custom value |
id | string | Tenant id |
plan | TargetValue | Tenant plan |
name | TargetValue | Tenant name |
KeyTarget
Parameter | Type | Description |
---|---|---|
key | TargetValue | The value to be matched |
TargetValue
Parameter | Type | Description |
---|---|---|
operator | Operator | The matching operator |
value | string | The value to be matched using the operator |
Operator
Operator | Description |
---|---|
eq | It should be equal to the value (==) |
beginsWith | It should begin with the value |
endsWith | It should end with the value |
contains | It should contain the value |
Feature flags flag
Model example:
{
"id": "64c64cfb47418500082f60b5",
"key": "iphone-feature",
"description": "A feature for iPhones",
"defaultValue": false,
"segments": [
{
"id": "64c63e7adaf20f0008e71b20",
"key": "iphones",
"description": "This segment targets iPhones",
"targets": [
{
"device": {
"key": "iphone"
}
}
]
}
],
"targetValue": true,
"enabled": true
}
Parameter | Type | Description |
---|---|---|
id | string | Unique ID (Read only) |
key | string | Flag key. Use this to reference the flag when evaluating |
description | string | Description text |
defaultValue | boolean | The value to return if no segment was found or matched |
segments | List of Segment | The segments and matchers that are linked to this flag |
targetValue | boolean | The value to return of a segment was matched |
enabled | boolean | Active state. Only enabled flags are available for evaluation. Otherwise evaluation falls back to false. |
Errors
Nblocks uses the following errors to explain what went wrong. All APIs use this error schema.
Error Code | Error message |
---|---|
NBLOCKS_CONFLICT | You cannot have two users with the same email in the same tenant. |
NBLOCKS_USER_NOT_FOUND | User not found. |
NBLOCKS_UNKNOWN_LOGIN_STRATEGY | Unknown login strategy. |
NBLOCKS_UNKNOWN_APP_ID | App Id is missing. |
NBLOCKS_APP_UNAUTHORIZED_EXCEPTION | App is unauthenticated. This usually means your APP API Key is not valid. |
NBLOCKS_UNAUTHORIZED_EXCEPTION | User is unathenticated. Please login first. |
INVALID_MFA_CODE_EXCEPTION | The MFA code your provided is invalid or expired. |
NBLOCKS_FORBIDDEN_EXCEPTION | You do not have access to this resource. |
NBLOCKS_FEATURE_FORBIDDEN_EXCEPTION | You do not have access to this feature. |
NBLOCKS_MISSING_CREDENTIALS | Missing required variables to authorize. |
NBLOCKS_MISSING_USERNAME | Missing username. |
NBLOCKS_MISSING_APP | Missing app. |
NBLOCKS_WRONG_CREDENTIALS | Wrong user credentials. |
NBLOCKS_INVALID_AUTH_TOKEN | Invalid auth token. |
NBLOCKS_INVALID_ROLE | The role you're changing to are not within your defined app roles. |
NBLOCKS_OWNER_ROLE_MUST_EXIST | Your app must have the role OWNER. |
NBLOCKS_NOT_FOUND_TENANT_EXCEPTION | Tenant do not exists |
NBLOCKS_MISSING_REQUIRED_VARIABLES_EXCEPTION | You're missing some required variables or the ones you've provided are not formated correctly |
NBLOCKS_INVALID_OAUTH_SCOPE_ERROR | The scope requested are not allowed for this client |
NBLOCKS_INVALID_REDIRECT_URI_ERROR | Invalid redirect_uri |
NBLOCKS_INVALID_GRANT_TYPE_ERROR | Unsupported grant_type |
NBLOCKS_INVALID_RESPONSE_TYPE_ERROR | Unsupported response_type |
NBLOCKS_STRIPE_OUT_OF_SYNC_EXCEPTION | It seems that the the data in your stripe account don't match your business model. Update your business model to resync the integration |
NBLOCKS_ERROR | An error occured. Please try again |
Changelog
September 2023
Nblocks Login * Passkeys support * Added signup flow
August 2023
- Launch of Feature flags.
Affected APIs:
- https://backendless.nblocks.cloud
- https://admin-api.nblocks.cloud
July 2023
- Brandning of User management portal with CSS and translations
Affected APIs:
- https://backendless.nblocks.cloud
June 2023
- Support for embedding User management portal
- Google SSO
Affected APIs:
- https://backendless.nblocks.cloud
- https://auth.nblocks.cloud
May 2023
- Introduction of Azure AD SSO and Azure Marketplace integration.
- Trial support for your plans
azureAdClientId
Affected APIs:
- https://auth.nblocks.cloud
- https://account-api.nebulr-core.com
April 2023
Improving onboarding information
Adding the onboarded
property to both tenantUser
and tenant
responses.
Affected APIs:
- https://auth.nblocks.cloud
- https://account-api.nebulr-core.com
March 2023
Brandable email templates
Enable developers to change the default email templates from the communication api to accomplish a fully customized branding.
getEmailTemplate
, overrideEmailTemplate
, resetEmailTemplate
.
Affected APIs:
- https://communication-api.nebulr-core.com
February 2023
Launching Auth service, Backendless and Cloud views.
Auth service: Oauth 2.0 login, JWTs and callback/handover functionality. Cloud views: Login flow so that any tech stack can use Nblocks login. Backendless: Powers cloud views but also any Nblocks UI plugin.
Adding the cloudviews
property to turn on/off this functionality to app
profile.
Affected APIs:
- https://auth.nblocks.cloud
- https://account-api.nebulr-core.com
October 2022
PDF generation
Affected APIs:
- https://file-api.nebulr-core.com
September 2022
Cloud hosted checkout view for simpler integration with Stripe
- https://account-api.nebulr-core.com
Affected APIs:
August 2022
File storage meta data cleansing support
Affected APIs:
- https://file-api.nebulr-core.com
May 2022
Launching voice call redirect api.
Now you can expose a phone number and configure a rule set how and to which recipients this call should be routed to.
Adding listVoiceRedirectRules
, createVoiceRedirectRule
, updateVoiceRedirectRule
, deleteVoiceRedirectRule
, listVoiceRedirectErrors
.
Affected APIs:
February 2022
- MFA support
January 2022
- Custom email sender
- Default role for new users
December 2021
Soft launch