Tenant Onboarding: Bootstrap a New Warehouse Company

Onboarding a new warehouse tenant in Dragon Guard is designed to be a single-request operation. The POST /api/supreme/companies endpoint accepts an optional bootstrap object that lets the Supreme administrator provision the entire tenant stack — company record, SaaS plan subscription, integration API key, tenant admin user, handheld operator user, default scanner device, and initial warehouse structure — without any follow-up calls. Each bootstrap component is independently optional; omit any section to skip that step.

Bootstrap endpoint

POST /api/supreme/companies
Authorization: Bearer <supreme-jwt>
Content-Type: application/json

Full bootstrap request example

{
  "code": "ACME",
  "name": "Acme Logistics",
  "legalName": "Acme Logistics S.A.",
  "taxId": "80012345-6",
  "email": "[email protected]",
  "userEmailDomain": "@acme.com",
  "phone": "+595 21 000 0000",
  "currencyCode": "USD",
  "timeZone": "America/Asuncion",
  "integrationMode": "GrupoMasNative",
  "planId": "00000000-0000-0000-0000-000000000001",
  "planStartsAt": "2025-01-01T00:00:00Z",
  "status": "Active",
  "apiAccessEnabled": true,
  "grupoMasNativeSettings": {
    "baseUrl": "https://erp.acme.com/api",
    "timeoutSeconds": 30,
    "apiKey": "erp-secret-key"
  },
  "bootstrap": {
    "locationCode": "MAIN",
    "locationName": "Main Warehouse",
    "binCode": "MAIN",
    "binDescription": "Main Bin",
    "tenantAdmin": {
      "email": "[email protected]",
      "fullName": "Jane Smith",
      "roleCode": "ADMIN",
      "password": null
    },
    "handheldOperator": {
      "email": "[email protected]",
      "fullName": "Carlos Mendez",
      "roleCode": "OPERATOR",
      "password": null
    },
    "handheldDevice": {
      "deviceId": "AA:BB:CC:DD:EE:FF",
      "deviceName": "Scanner 01",
      "isActive": true
    }
  }
}

How the bootstrap works

Create the company

The company record is created with all supplied fields. code and name are required. code must be unique — the API returns 409 Conflict with COMPANY_CODE_ALREADY_EXISTS if it is already taken. An integration API key is generated immediately; its hash is stored and the plain key is returned once in the response.

Assign the plan

If planId is provided, the plan is looked up and the subscription is initialized in a single step:

PlanStartsAt is set to planStartsAt (or UtcNow if omitted).
PlanExpiresAt is derived from PlanStartsAt plus the plan’s renewalPeriod.
PlanStatus is set to Active.
DeviceLimit is initialized to the plan’s maxHandheldDevices.
A CompanyPlanAudit record is written.

If no planId is supplied, the tenant is created with PlanStatus = Active and DeviceLimit = null (falls back to the plan default once assigned later).

Generate integration API key

A cryptographically random API key is generated. The ApiKeyHash (BCrypt) is stored on the company record. The plain text key is included in the create response under apiKey and is never retrievable again from any read endpoint.

Create tenant admin

If bootstrap.tenantAdmin is provided, a user is created (or reused if the email already exists in auth.Users) and assigned the specified roleCode for this tenant. The default role for admin bootstrap is ADMIN.

If password is null or omitted, the system generates the temporary password 123456.
MustChangePassword is set to true — the user must change their password on first login.
The plain temporary password is returned once in the response under tenantAdmin.temporaryPassword.

Create handheld operator

If bootstrap.handheldOperator is provided, a second user is created with roleCode = OPERATOR (or the specified role). The same temporary password rules apply. The plain password is returned once under handheldOperator.temporaryPassword.

Pre-register handheld device

If bootstrap.handheldDevice is provided, the device MAC address is normalized to uppercase colon-separated format (AA:BB:CC:DD:EE:FF) and inserted into core.HandheldDevices for the new tenant. The isActive flag determines whether login is immediately permitted.If the company’s deviceLimit is 0, the bootstrap will fail with plans.deviceLimitExceeded. Ensure deviceLimit ≥ 1 before registering a device.

Bootstrap warehouse defaults

A default location and a default bin are created for the tenant. If bootstrap.locationCode / bootstrap.binCode are omitted, they default to MAIN. These records are marked as the tenant’s default location and default bin, satisfying the operational requirement for receipts, shipments, and integration flows that rely on a default location context.

Request fields reference

Top-level company fields

code

string

required

Short tenant code (e.g., ACME). Must be unique across all companies. For GrupoMAS Native tenants this maps to codigo_empresa in Grupo Mas.

name

string

required

Display name of the company.

userEmailDomain

string

required

Enforced email domain for all users of this tenant (e.g., @acme.com). New user creation will reject emails that do not end with this domain.

integrationMode

string

One of Standalone, GrupoMasNative, or BusinessCentralNative. Defaults to Standalone.

planId

guid

ID of the SaaS plan to assign at creation time. Optional — the tenant can be assigned a plan later via POST /api/supreme/companies/{tenantId}/plans/assign.

planStartsAt

datetime

UTC start date for the plan subscription. Defaults to the moment of creation if omitted.

status

string

Initial company status: Active, Inactive, or Suspended. Defaults to Active.

apiAccessEnabled

boolean

Whether integration API access is enabled for this tenant from day one.

deviceLimit

integer

Optional company-level override for the maximum number of active handheld devices. When omitted, the plan’s maxHandheldDevices value applies.

Integration settings

grupoMasNativeSettings

object

Connection settings for GrupoMAS Native integration. Required when integrationMode = GrupoMasNative.

Show grupoMasNativeSettings fields

baseUrl

string

Base URL of the GrupoMAS API (e.g., https://erp.acme.com/api).

timeoutSeconds

integer

HTTP request timeout in seconds. Defaults to the system default if omitted.

apiKey

string

API key credential for the GrupoMAS endpoint. Mutually exclusive with bearerToken.

bearerToken

string

Bearer token credential. Mutually exclusive with apiKey.

businessCentralNativeSettings

object

Connection settings for Business Central Native integration. Required when integrationMode = BusinessCentralNative.

Show businessCentralNativeSettings fields

baseUrl

string

Business Central API base URL.

tenantId

string

Azure AD tenant ID.

environmentName

string

Business Central environment name (e.g., Production).

companyId

string

Business Central company GUID.

companyName

string

Business Central company display name.

timeoutSeconds

integer

HTTP request timeout in seconds.

accessKey

string

Web service access key credential.

Bootstrap object

bootstrap.locationCode

string

Code for the default warehouse location. Defaults to MAIN if omitted.

bootstrap.locationName

string

Display name for the default location. Defaults to MAIN if omitted.

bootstrap.binCode

string

Code for the default bin within the default location. Defaults to MAIN if omitted.

bootstrap.binDescription

string

Description for the default bin.

bootstrap.tenantAdmin

object

Optional. Creates an admin user for the tenant.

Show tenantAdmin fields

string

required

Must match the tenant’s userEmailDomain if configured.

fullName

string

required

Full name for the user record.

roleCode

string

Tenant role. Accepted: ADMIN, SUPERVISOR, OPERATOR. Defaults to ADMIN.

password

string

Optional initial password. If null, the temporary password 123456 is used.

bootstrap.handheldOperator

object

Optional. Creates a second user intended for handheld device login. Accepts the same fields as tenantAdmin. Defaults roleCode to OPERATOR.

bootstrap.handheldDevice

object

Optional. Pre-authorizes a physical handheld device for this tenant.

Show handheldDevice fields

deviceId

string

required

MAC address of the device. Normalized to AA:BB:CC:DD:EE:FF format automatically.

deviceName

string

Friendly name for the device (e.g., Scanner 01).

isActive

boolean

Whether the device is authorized for login immediately. Defaults to true.

Create response

{
  "companyId": "...",
  "companyCode": "ACME",
  "companyName": "Acme Logistics",
  "isActive": true,
  "status": "Active",
  "planId": "...",
  "planName": "Pro",
  "planStatus": "Active",
  "planStartsAt": "2025-01-01T00:00:00Z",
  "planExpiresAt": "2025-02-01T00:00:00Z",
  "deviceLimit": 5,
  "integrationMode": "GrupoMasNative",
  "integrationProvider": "GrupoMasNative",
  "apiAccessEnabled": true,
  "externalSystem": null,
  "notes": null,
  "apiKey": "dg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "apiKeyVisibleOnce": true,
  "defaultLocationCode": "MAIN",
  "defaultBinCode": "MAIN",
  "tenantAdmin": {
    "userId": "...",
    "email": "[email protected]",
    "fullName": "Jane Smith",
    "roleCode": "ADMIN",
    "created": true,
    "temporaryPassword": "123456",
    "mustChangePassword": true
  },
  "handheldOperator": {
    "userId": "...",
    "email": "[email protected]",
    "fullName": "Carlos Mendez",
    "roleCode": "OPERATOR",
    "created": true,
    "temporaryPassword": "123456",
    "mustChangePassword": true
  },
  "handheldDevice": {
    "deviceId": "...",
    "deviceKey": "AA:BB:CC:DD:EE:FF",
    "deviceName": "Scanner 01",
    "isActive": true
  }
}

The apiKey and any temporaryPassword values are returned exactly once in this response. They are not stored in plain text and cannot be retrieved from any read endpoint. Copy them immediately and distribute them securely to the tenant.

Document sequences

Creating a company also seeds the following document sequence counters for the tenant, starting at zero:

Document Type	Purpose
`ITEM_CREATED`	Item master auto-numbering
`RECEIPT_CREATED`	Receiving header numbering
`POSTED_RECEIVE`	Posted receipt numbering
`SHIPMENT_CREATE`	Shipment header numbering
`POSTED_SHIPMENT`	Posted shipment numbering
`PURCHASE_ORDER`	Purchase order numbering
`SALES_ORDER`	Sales order numbering

These sequences are initialized automatically and require no manual configuration.

Company.Code is required for GrupoMAS Native tenants. It maps directly to codigo_empresa in the Grupo Mas ERP integration. Set it to the exact code configured in the ERP system before enabling polling.

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Tenant Onboarding: Bootstrap a New Warehouse Company

Bootstrap endpoint

Full bootstrap request example

How the bootstrap works

Request fields reference

Top-level company fields

Integration settings

Bootstrap object

Create response

Document sequences

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Bootstrap endpoint

​Full bootstrap request example

​How the bootstrap works

​Request fields reference

​Top-level company fields

​Integration settings

​Bootstrap object

​Create response

​Document sequences

Build docs developers (and LLMs) love

Bootstrap endpoint

Full bootstrap request example

How the bootstrap works

Request fields reference

Top-level company fields

Integration settings

Bootstrap object

Create response

Document sequences