Managing Tenant Companies and SaaS Plans in Dragon Guard

The Supreme layer exposes a full management surface for tenant companies and SaaS plan definitions. Companies represent isolated warehouse tenants; plans define the operational limits — device count, user cap, location cap, billing period — that govern each tenant’s subscription. All endpoints in this section require a valid SUPERADMIN_SUPREMO JWT.

Companies

List all companies

GET /api/supreme/companies
Authorization: Bearer <supreme-jwt>

Returns an array of SupremeCompanyDto objects ordered alphabetically by company name. Each object carries the SaaS metadata most relevant for a dashboard view: plan assignment, plan dates, integration mode, and API access flag. Response fields (per company):

guid

Unique company identifier.

code

string

Short tenant code. Used as the codigo_empresa mapping for GrupoMAS Native tenants.

name

string

Display name of the tenant company.

legalName

string | null

Full legal name of the tenant company, if provided.

taxId

string | null

Tax identification number for the tenant, if provided.

string | null

Primary billing or contact email for the tenant.

userEmailDomain

string | null

Enforced email domain for all users of this tenant (e.g., @acme.com).

phone

string | null

Contact phone number for the tenant.

status

string

Current SaaS status: Active, Inactive, or Suspended.

isActive

boolean

Derived from status. true only when status = Active.

planId

guid | null

The assigned SaaS plan. null if no plan has been assigned.

planName

string | null

Human-readable name of the assigned plan.

planStartsAt / planExpiresAt

datetime | null

Subscription window. null for tenants without a plan or unlimited plans.

planStatus

string

Subscription status: Active, Expiring, Expired, or Demo.

integrationMode

string

Normalized integration mode: Standalone, GrupoMasNative, or BusinessCentralNative.

integrationProvider

string

Resolved integration provider name (e.g., Standalone, GrupoMasNative, BusinessCentralNative).

apiAccessEnabled

boolean

Whether the tenant is allowed to use integration API access.

createdAt

datetime

UTC timestamp when the company record was created.

createdBy

string | null

Email of the Supreme administrator who created the record.

updatedAt

datetime | null

UTC timestamp of the last update, if any.

updatedBy

string | null

Email of the Supreme administrator who last updated the record.

Get company detail

GET /api/supreme/companies/{id}
Authorization: Bearer <supreme-jwt>

Returns a SupremeCompanyDetailDto, which extends the list DTO with full operational and integration settings. Additional fields in the detail response:

address1 / city / country

string | null

Physical address fields for the tenant.

currencyCode

string

Default currency for the tenant. Defaults to USD.

timeZone

string

IANA time zone identifier. Defaults to UTC.

isWmsEnabled

boolean

Whether the WMS operational modules are active for this tenant.

allowNegativeStock

boolean

Whether the tenant is permitted to drive inventory below zero.

grupoMasNativeSettings

object | null

Present when integrationProvider = GrupoMasNative. Contains baseUrl, timeoutSeconds, polling configuration, and masked credential indicators.

businessCentralNativeSettings

object | null

Present when integrationProvider = BusinessCentralNative. Contains baseUrl, tenantId, environmentName, companyId, companyName, and masked access key indicator.

rfidSettings

object | null

RFID feature flags: enabled, mode (Disabled, InquiryOnly, OperationalAssist, StrictValidation), and per-module toggles for receipts, shipments, and movements.

deviceLimit

integer | null

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

hasApiKey

boolean

true if a hashed API key exists. The plain key is never returned by this endpoint.

userCount

integer

Total number of users assigned to this tenant.

roleCodes

string[]

Distinct role codes present among this tenant’s users (e.g., ["ADMIN", "OPERATOR"]).

Create company

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

Creates a new tenant company and immediately generates an API key. Optionally accepts a bootstrap object to pre-configure users, a device, and warehouse defaults in the same request. See Tenant Onboarding for the full bootstrap flow. Minimal body:

{
  "code": "ACME",
  "name": "Acme Logistics",
  "userEmailDomain": "@acme.com",
  "integrationMode": "Standalone",
  "status": "Active"
}

Validation rules:

code and name are required.
code must be unique across all companies. Returns 409 Conflict with COMPANY_CODE_ALREADY_EXISTS if taken.
userEmailDomain must be a valid domain format (e.g., @acme.com). Returns 400 with validation.tenantEmailDomainInvalid if malformed.
planId, if provided, must reference an existing SaaSPlans record. Returns 400 PLAN_NOT_FOUND if not found.
GrupoMAS Native tenants (integrationMode = GrupoMasNative) require a non-empty code.

Returns 201 Created with the full create response including the one-time plain API key.

Update company

PUT /api/supreme/companies/{id}
Authorization: Bearer <supreme-jwt>
Content-Type: application/json

Full replacement update for a company record. Accepts the same body as POST /api/supreme/companies (without bootstrap). Integration settings use preserveExistingWhenNull: true — omitting a settings object leaves those fields unchanged. Returns 204 No Content on success.

Change company status

PATCH /api/supreme/companies/{id}/status
Authorization: Bearer <supreme-jwt>
Content-Type: application/json

{
  "status": "Suspended"
}

Accepted values: Active, Inactive, Suspended. The isActive flag is synchronized automatically:

Status	IsActive
`Active`	`true`
`Inactive`	`false`
`Suspended`	`false`

Returns 204 No Content.

When a tenant’s status is Suspended, write operations in the operational WMS modules return 402 Payment Required. Read operations remain available so the tenant can still export their data.

Toggle integration API access

PATCH /api/supreme/companies/{id}/integration-access
Authorization: Bearer <supreme-jwt>
Content-Type: application/json

{
  "apiAccessEnabled": true
}

Enables or disables the tenant’s ability to use the integration API. Does not affect the API key itself. Returns 204 No Content.

Regenerate integration API key

POST /api/supreme/companies/{id}/integration/regenerate-key
Authorization: Bearer <supreme-jwt>

Generates a new API key for the tenant. The plain key is returned once only in the response body; only the ApiKeyHash is stored. Any previous key is immediately invalidated.

Copy the plain key from the response immediately. It cannot be retrieved again from any read endpoint — GET /api/supreme/companies/{id} only indicates whether a key exists (hasApiKey: true).

{
  "apiKey": "dg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "apiKeyVisibleOnce": true
}

Plans

List all plans

GET /api/supreme/plans
Authorization: Bearer <supreme-jwt>

Returns all SaaS plans (active and inactive), ordered alphabetically by name. The commercial public catalog is available separately at GET /api/plans/catalog (non-Supreme, returns only active non-demo plans). Response fields (per plan):

guid

Unique plan identifier.

name

string

Plan display name (e.g., Basic, Pro, Enterprise).

maxHandheldDevices

integer

Maximum number of simultaneously active handheld devices allowed under this plan.

maxUsers

integer

Maximum number of user accounts for tenants on this plan.

maxLocations

integer

Maximum warehouse locations for tenants on this plan.

price

decimal

Subscription price per renewal period.

currencyCode

string

Billing currency: USD or PYG.

renewalPeriod

string

Billing cycle: Weekly, Monthly, Quarterly, Semiannual, or Annual.

isActive

boolean

Whether the plan is publicly available for assignment. Inactive plans are hidden from the public catalog but remain visible here.

isDemo

boolean

Demo plans are protected from destructive edits and can only be assigned once per tenant.

displayOrder

integer

Sort order used for display in the public plan catalog.

description

string | null

Optional short description of the plan.

monthlyLimit

integer | null

Optional monthly transaction cap, if the plan enforces a limit.

benefits

string[]

List of marketing benefit strings shown in the plan catalog.

activeCompanies

integer

Number of companies currently assigned to this plan.

createdAt

datetime

UTC timestamp when the plan was created.

Create plan

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

{
  "name": "Pro",
  "maxHandheldDevices": 5,
  "maxUsers": 20,
  "maxLocations": 10,
  "price": 299.00,
  "currencyCode": "USD",
  "renewalPeriod": "Monthly",
  "isActive": true,
  "displayOrder": 2,
  "description": "For mid-size warehouses with multiple scanning stations.",
  "benefits": ["Up to 5 handheld devices", "20 users", "10 locations"]
}

Validation rules:

name is required.
name must be unique across all plans. Returns 409 Conflict with PLAN_NAME_ALREADY_EXISTS if already taken.
maxHandheldDevices must be ≥ 1.
price must be ≥ 0.
currencyCode must be USD or PYG.
renewalPeriod must be one of Weekly, Monthly, Quarterly, Semiannual, Annual.

Returns 201 Created with { "id": "<new-plan-guid>" }.

Update plan

PUT /api/supreme/plans/{id}
Authorization: Bearer <supreme-jwt>
Content-Type: application/json

Accepts the same body as POST /api/supreme/plans. Demo plans (isDemo = true) are protected — attempts to update them return 400 with plans.demoProtected. Returns 204 No Content.

Assign plan to tenant

POST /api/supreme/companies/{tenantId}/plans/assign
Authorization: Bearer <supreme-jwt>
Content-Type: application/json

{
  "planId": "00000000-0000-0000-0000-000000000001",
  "startsAt": "2025-01-01T00:00:00Z",
  "comment": "Upgraded from Basic to Pro"
}

Assigns a plan to an existing tenant and initializes the subscription window. This action also:

Sets PlanStartsAt, PlanExpiresAt (derived from plan’s renewalPeriod), and PlanStatus.
Updates DeviceLimit to the plan’s maxHandheldDevices.
Updates Company.Status and Company.IsActive if the resolved plan status is Suspended.
Writes a CompanyPlanAudit record for traceability.

Demo plans can only be assigned once per tenant; a second attempt returns 400 with plans.demoAlreadyUsed. Returns 200 OK with the tenant’s updated plan status (TenantPlanStatusDto).

View plan assignment history

GET /api/supreme/companies/{tenantId}/plans/history
Authorization: Bearer <supreme-jwt>

Returns an ordered audit log of all plan assignments and changes for the tenant, including action, oldState, newState, and createdBy.

Tenant Users

List users for a tenant

GET /api/supreme/companies/{tenantId}/users
Authorization: Bearer <supreme-jwt>

Returns all users assigned to the specified tenant. Includes user identity, role code, active status, and last login metadata.

Create a tenant admin user

POST /api/supreme/companies/{tenantId}/users/admin
Authorization: Bearer <supreme-jwt>
Content-Type: application/json

{
  "email": "[email protected]",
  "fullName": "Jane Smith",
  "roleCode": "ADMIN",
  "password": null
}

string

required

Email address for the new user. Must match the tenant’s configured userEmailDomain if one is set.

fullName

string

required

Full display name of the user.

roleCode

string

Role to assign. Accepted values: ADMIN, SUPERVISOR, OPERATOR. Defaults to ADMIN for this endpoint.

password

string

Optional initial password. If omitted, the system generates the temporary password 123456. The first login will require a password change regardless.

If the email already exists in auth.Users, the existing user record is reused and only the tenant role assignment is added. A user cannot be assigned to more than one tenant — attempting to do so returns 409 Conflict with auth.userAssignedToOtherTenant. Response:

{
  "userId": "...",
  "email": "[email protected]",
  "fullName": "Jane Smith",
  "roleCode": "ADMIN",
  "created": true,
  "temporaryPassword": "123456",
  "mustChangePassword": true
}

userId

guid

ID of the user record in auth.Users.

string

Email address of the created or reused user.

fullName

string

Full display name of the user.

roleCode

string

Tenant role assigned to the user (e.g., ADMIN, OPERATOR).

created

boolean

true if a new user account was created; false if an existing auth.Users record was reused and only the tenant role assignment was added.

temporaryPassword

string | null

The plain-text temporary password. null if a custom password was supplied or the user already existed. Stored as a BCrypt hash — cannot be retrieved again.

mustChangePassword

boolean

Always true. The user must change their password on first login.

The temporaryPassword field is returned only in this response. It is stored as a BCrypt hash and cannot be retrieved again.

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Managing Tenant Companies and SaaS Plans in Dragon Guard

Companies

List all companies

Get company detail

Create company

Update company

Change company status

Toggle integration API access

Regenerate integration API key

Plans

List all plans

Create plan

Update plan

Assign plan to tenant

View plan assignment history

Tenant Users

List users for a tenant

Create a tenant admin user

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Companies

​List all companies

​Get company detail

​Create company

​Update company

​Change company status

​Toggle integration API access

​Regenerate integration API key

​Plans

​List all plans

​Create plan

​Update plan

​Assign plan to tenant

​View plan assignment history

​Tenant Users

​List users for a tenant

​Create a tenant admin user

Build docs developers (and LLMs) love

Companies

List all companies

Get company detail

Create company

Update company

Change company status

Toggle integration API access

Regenerate integration API key

Plans

List all plans

Create plan

Update plan

Assign plan to tenant

View plan assignment history

Tenant Users

List users for a tenant

Create a tenant admin user