Super Admin API

Platform-wide operations that cross tenant boundaries: creating tenants, defining the base domain they sit under, and imposing one sign-in or sharing policy on all of them. For operations inside a single tenant, see Admin.

Base URL and authorization

/api/external/v1/super-admin

These endpoints require an API Key issued to an account holding the SUPER_ADMIN role. An ordinary administrator's key does not pass.

Scope is not checked here either

Like the admin endpoints, authorization is by role alone. A key holding only api:read can create tenants, change the base domain, and enforce policy across every tenant. A super administrator key is the most privileged credential in the system regardless of the scope it was issued with.

Tenant entry-key issuance is internal and is not exposed through the external API.

Base domain

Tenants are addressed as a subdomain of one shared base domain.

GET /api/external/v1/super-admin/base-domain
PUT /api/external/v1/super-admin/base-domain

Parameter	Type	Required	Description
bd	string	Yes	Base domain, up to 253 characters

Only one base domain is supported, and it is always baseDomainSeq 1.

Changing it rewrites every tenant's address

Setting the base domain recalculates the full domain of every registered tenant. Existing tenant URLs stop resolving at their old addresses. Plan for DNS, certificates, and any hard-coded client URLs before changing it.

An invalid domain returns BASE_DOMAIN_002, and reading before one is configured returns BASE_DOMAIN_001.

List tenants

GET /api/external/v1/super-admin/tenants

Parameter	Type	Required	Description
ps	integer	Yes	Page size, minimum 1
ci	long	No	Cursor - the last tenantSeq of the previous page

Each entry reports tenantSeq, tenantName, domain, clientUrl, registerDate, and license. The licence summary is null for a tenant with none, and otherwise carries state, expiresOn, and a seat object of current and max - enough to spot expired or over-subscribed tenants without reading each one.

Read a tenant

GET /api/external/v1/super-admin/tenants/{tenantSeq}

Returns tenantName, subdomain, baseDomainSeq, and allowedIps. An unknown tenant returns TENANT_001.

Note that the listing returns the assembled domain while this endpoint returns the subdomain it was built from.

Create a tenant

POST /api/external/v1/super-admin/tenants

Creates the tenant, its first administrator, and its IP allowlist in one call.

Parameter	Type	Required	Description
tn	string	Yes	Tenant name
sd	string	Yes	Subdomain, up to 253 characters
bs	integer	Yes	Base domain seq
e	string	Yes	Administrator account id, an email address
n	string	Yes	Administrator display name
p	string	Yes	Administrator password
ips	array	No	Allowed IPv4 addresses or CIDR ranges

Create tenant

curl -X POST "https://drive.example.com/api/external/v1/super-admin/tenants" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"tn": "Example", "sd": "example", "bs": 1, "e": "admin@example.com", "n": "Administrator", "p": "Test1234!", "ips": ["192.168.0.12", "192.168.0.0/24"]}'

The new tenant starts with a default system configuration: the office domain and adapter name are set, Intellect and sharing are on, and MFA is off. Change these through the tenant's own Admin endpoints.

A subdomain already in use returns TENANT_006, a malformed one returns TENANT_007, and a bs that does not exist returns BASE_DOMAIN_001.

Update a tenant

PATCH /api/external/v1/super-admin/tenants/{tenantSeq}

Parameter	Type	Required	Description
tn	string	Yes	Tenant name
sd	string	Yes	Subdomain, up to 253 characters
bs	integer	Yes	Base domain seq
ips	array	No	Allowed IPv4 addresses or CIDR ranges

All three of tn, sd, and bs are required even when you are changing only one of them, so read the tenant first and resend its current values. Changing sd changes the tenant's address.

Sign-in policy

The same sign-in configuration as the tenant-level endpoint, with the addition that a super administrator can impose it on every tenant at once.

GET /api/external/v1/super-admin/login-settings
PUT /api/external/v1/super-admin/login-settings

Reading accepts s to choose the scope - tenant or global - and l to filter by login type.

Parameter	Type	Required	Description
ie	boolean	Yes	true applies this setting to every tenant; false leaves each tenant to its own
l	string	No	Login type - local, oidc, or jwt
ps	array	No	Identity providers

Providers and their config objects take exactly the same fields as the tenant-level endpoint described in Admin, including the requirement that config.type equals the login type. The same SSO_PROTOCOL_001 and SSO_PROTOCOL_002 errors apply.

The field names differ from the tenant endpoint

This endpoint uses l and ps where the tenant endpoint uses loginType and providers, and adds ie. The read response reports isEnforced rather than superAdminEnforced. The config objects are identical.

The read endpoint returns secrets in clear text

As at tenant level, clientSecret and publicKey come back unmasked. Keep the response server-side.

Sharing policy

GET /api/external/v1/super-admin/share-settings
PUT /api/external/v1/super-admin/share-settings

Parameter	Type	Required	Description
e	boolean	Yes	true applies this setting to every tenant; false leaves each tenant to its own
se	boolean	Conditional	Whether sharing is available; required when e is true
esa	boolean	Conditional	Allow sharing outside the organization; required when e and se are true
sua	boolean	Conditional	Allow the SPECIFIC_USERS share type; required when e and se are true
ola	boolean	Conditional	Allow the ORG_LINK share type; required when e and se are true
pa	boolean	Conditional	Allow the PUBLIC_LINK share type; required when e and se are true

When enforcing with sharing on, at least one of sua, ola, and pa must be true, and enabling pa requires esa to be true as well - the same rules as the tenant endpoint.

While e is true, every tenant's own share settings endpoint reports isEnforced and returns these global values instead of its own. Setting e back to false returns each tenant to the settings it had.

Errors

See Errors for the full list of codes these endpoints return.