Tenant Administration Guide

This guide covers day-to-day tenant administration: creating organizations, managing users, configuring groups, and applying org-level security policies. For the underlying data isolation model, see Data Isolation Guide.

Organization model

Arbitex uses an implicit organization model. There is no standalone “organizations” table on the Platform — instead, a tenant_id UUID is assigned to users and propagated to all org-scoped resources (groups, DLP rules, audit logs, policies). The Cloud Portal maintains an explicit organizations table that maps each org to its Platform tenant_id.

Initial setup

The first organization is created during platform setup:

POST /api/setup/complete

Field	Type	Description
`admin.username`	string	First admin username
`admin.email`	string	First admin email
`admin.password`	string	First admin password
`org_name`	string (optional)	Organization display name (stored as system config)
`provider.name`	string (optional)	Initial AI provider name
`provider.api_key`	string (optional)	Initial provider API key
`default_model`	string (optional)	Default model for the org

This endpoint is guarded by a zero-user check — it only works when the database has no users. After setup, the initial admin can invite additional users.

User management

Roles

Arbitex has two platform roles:

Role	Capabilities
`admin`	Full access to admin endpoints — user management, group CRUD, DLP configuration, policy management, system config
`user`	Standard access — chat, view own profile, use API keys

Admins can only manage resources within their own tenant_id. There is no cross-tenant super-admin role.

Inviting users

Users join an organization through admin-issued invitations:

POST /api/v1/admin/users/invite

Field	Type	Description
`email`	string	Invitee email address

The invitation:

Creates a UserPendingInvite record scoped to the admin’s tenant_id
Generates a unique token (UUID)
Expires after 7 days
Is recorded in the audit log

Managing invitations:

Endpoint	Method	Description
`/api/v1/admin/users/invites`	GET	List pending invitations for your org
`/api/v1/admin/users/invites/{invite_id}`	DELETE	Cancel an invitation (sets status to CANCELLED)

Managing existing users

Endpoint	Method	Description
`/api/v1/admin/users`	GET	List all users in your org
`/api/v1/admin/users/{user_id}/role`	PUT	Change role (`admin` or `user`)
`/api/v1/admin/users/{user_id}/active`	PUT	Enable or disable a user account
`/api/v1/admin/users/{user_id}/avatar`	PATCH	Set user avatar (256×256 WebP, 2 MB max)

Constraints:

You cannot change your own role
You cannot deactivate your own account
Deactivation uses is_active=false (soft disable) — the user record and audit history are preserved

User registration

POST /api/auth/register is an open endpoint. Users who register without an invitation do not have a tenant_id assigned — tenant membership is set administratively.

Group management

Groups are the primary scoping unit for DLP overrides, model access, compliance bundles, and policy conditions. See User & Group Management for the full reference.

Group CRUD

Endpoint	Method	Description
`/api/v1/admin/groups`	POST	Create group (name unique within tenant)
`/api/v1/admin/groups`	GET	List groups in your org
`/api/v1/admin/groups/{group_id}`	GET	Get group details
`/api/v1/admin/groups/{group_id}`	PUT	Update group name or description
`/api/v1/admin/groups/{group_id}`	DELETE	Delete group

Group membership

Endpoint	Method	Description
`/api/v1/admin/groups/{group_id}/members`	GET	List group members
`/api/v1/admin/groups/{group_id}/members`	POST	Add member (`{user_id}`)
`/api/v1/admin/groups/{group_id}/members/{user_id}`	DELETE	Remove member

Groups can also be provisioned automatically via SCIM from an IdP (Entra ID, Okta). Set external_group_id on the group to link it to an IdP group for automatic membership sync.

Per-group DLP configuration

Each group can override the org-level DLP detector actions:

Endpoint	Method	Description
`/api/v1/admin/groups/{group_id}/dlp`	GET	List DLP overrides for group
`/api/v1/admin/groups/{group_id}/dlp`	PUT	Replace all DLP overrides (full replacement)

Override actions per detector: SKIP, BLOCK, CANCEL, REDACT. Group-level overrides take precedence over the org-level default.

Per-group model access

Endpoint	Method	Description
`/api/v1/admin/groups/{group_id}/model-access`	GET	List model access rules
`/api/v1/admin/groups/{group_id}/model-access`	POST	Add allow/deny rule for a model
`/api/v1/admin/groups/{group_id}/model-access/{model_id}`	DELETE	Remove rule
`/api/v1/admin/model-access/org-defaults`	GET	List org-level default model access
`/api/v1/admin/model-access/org-defaults`	POST	Add org-level default
`/api/v1/admin/model-access/org-defaults/{model_id}`	DELETE	Remove org-level default

Policy resolution

When a user belongs to multiple groups, policy resolution uses a 3-tier cascade: System Default → Group → User. For conflicting group rules, the most restrictive value wins (lowest quota, DENY overrides ALLOW for model access).

DLP configuration per org

Organizations can customize the DLP pipeline beyond the platform defaults.

Org-level DLP rules

Endpoint	Method	Description
`/api/orgs/{org_id}/dlp-rules/effective`	GET	Merged view: platform defaults + org overrides (suppressions marked)
`/api/orgs/{org_id}/dlp-rules/`	GET	List org-specific rules (paginated)
`/api/orgs/{org_id}/dlp-rules/`	POST	Create custom pattern or suppress a default rule
`/api/orgs/{org_id}/dlp-rules/{rule_id}`	GET	Get rule details
`/api/orgs/{org_id}/dlp-rules/{rule_id}`	PUT	Update rule
`/api/orgs/{org_id}/dlp-rules/{rule_id}`	DELETE	Soft-delete rule

Rule types

Type	Description
`custom_pattern`	Custom regex pattern with a configurable entity label and action tier
`suppress_default`	Disables a platform built-in detector for this org

Action tiers

Tier	Behavior
`log_only`	Detect and log; do not modify the request
`redact`	Replace matched content with a placeholder
`block`	Reject the request entirely
`prompt`	Log and flag for human review

DLP rule layering

DLP rules are evaluated in three layers:

Platform defaults — built-in detectors (SSN, credit card, API key patterns, etc.)
Org overrides — custom patterns added; default detectors suppressed
Group overrides — per-detector action changes for specific groups

All changes to org DLP rules are recorded in org_dlp_rule_audit with before/after snapshots.

Security policies per org

MFA enforcement

Endpoint	Method	Description
`/api/v1/admin/org/mfa-policy`	GET	Get current enforcement level
`/api/v1/admin/org/mfa-policy`	PUT	Set enforcement level

Enforcement levels: off (default), encouraged, required. Changes take effect immediately (in-memory cache cleared on update, 60-second cache TTL for reads).

Passkey policy

Endpoint	Method	Description
`/api/v1/admin/org/passkey-policy`	GET	Get passkey enforcement level
`/api/v1/admin/org/passkey-policy`	PUT	Set passkey enforcement level

Levels: off (default), encouraged, required.

Account recovery

Endpoint	Method	Description
`/api/v1/admin/org/recovery-policy`	GET	Get recovery method toggles
`/api/v1/admin/org/recovery-policy`	PUT	Set recovery method toggles

Field	Type	Default	Description
`admin_recovery_enabled`	boolean	`true`	Admins can initiate recovery for users
`self_service_recovery_enabled`	boolean	`false`	Users can self-service recover

IP allowlist

Endpoint	Method	Description
`/v1/org/ip-allowlist`	GET	List allowlist entries
`/v1/org/ip-allowlist`	POST	Add CIDR, range, or single IP entry
`/v1/org/ip-allowlist/{entry_id}`	PATCH	Update entry
`/v1/org/ip-allowlist/{entry_id}`	DELETE	Remove entry

IP allowlisting is enforced at middleware layer 9 in the security stack. Admin ports are exempt by default.

SSO identity providers

Each org can configure its own SAML 2.0 identity provider:

Endpoint	Method	Description
`/api/v1/admin/saml/idp`	POST	Create IdP configuration
`/api/v1/admin/saml/idp`	GET	List all IdP configs
`/api/v1/admin/saml/idp/{idp_id}`	GET	Get IdP details
`/api/v1/admin/saml/idp/{idp_id}`	PUT	Update IdP configuration
`/api/v1/admin/saml/idp/{idp_id}`	DELETE	Delete IdP

IdP configuration fields:

Field	Type	Description
`name`	string	Display name (e.g., “Okta Production”)
`entity_id`	string	SAML entity ID (unique)
`sso_url`	string	SSO service URL (HTTP-Redirect binding)
`slo_url`	string (optional)	Single Logout URL
`x509_cert`	text	PEM-encoded certificate for signature verification
`attribute_mapping`	JSON	Maps IdP attributes to Arbitex fields (`email`, `username`, `groups`)
`is_active`	boolean	Enable/disable this IdP

SAML IdP configs are scoped to tenant_id — each org has its own SSO configuration, independent of other tenants.

SCIM provisioning

SCIM 2.0 endpoints at /scim/v2/ support automated user and group provisioning from your IdP:

Endpoint prefix	Resources
`/scim/v2/Users`	User CRUD with GET, POST, PUT, PATCH, DELETE
`/scim/v2/Groups`	Group CRUD with GET, POST, PUT, PATCH, DELETE
`/scim/v2/ServiceProviderConfig`	SCIM capabilities discovery
`/scim/v2/ResourceTypes`	Resource type discovery
`/scim/v2/Schemas`	Schema discovery

SCIM authentication uses per-org bearer tokens stored as bcrypt hashes. Token rotation:

POST /api/v1/scim/token/rotate

The endpoint rotates the token for the authenticated admin’s own org — the target org is derived from the credential you authenticate with. There is no org identifier in the path, body, or headers.

The new token is returned only once — it is stored as a hash and cannot be retrieved again.

See SCIM Provisioning for setup instructions.

Plan management

Plan tiers

Tier	Request limit	Key features
DevFree SaaS	100,000/month	Shared SaaS, row-level isolation
DevPro SaaS	1,000,000/month	Shared SaaS, row-level isolation
Team SaaS	1,000,000/month	Shared SaaS, row-level isolation
Enterprise SaaS	Custom	Shared SaaS, custom limits, compliance bundles
Enterprise Outpost	Custom	Dedicated data plane, custom limits

Usage monitoring

GET /api/orgs/{org_id}/usage

Returns current-period request count, plan quota, and remaining capacity.

Enterprise entitlements

Enterprise orgs can have custom overrides:

Field	Type	Description
`custom_request_limit`	integer	Overrides tier default request limit
`custom_rate_limit_rpm`	integer	Overrides tier default rate limit (requests/minute)
`custom_compliance_set`	JSON array	Additional compliance bundle IDs

Data retention

Admins can configure per-table retention policies to automatically purge aged data:

Endpoint	Method	Description
`/api/v1/admin/retention-policies`	GET	List retention policies for your org
`/api/v1/admin/retention-policies`	POST	Create a retention policy
`/api/v1/admin/retention-policies/{id}`	GET	Get policy details
`/api/v1/admin/retention-policies/{id}`	PUT	Update retention days or enabled status
`/api/v1/admin/retention-policies/{id}`	DELETE	Delete policy
`/api/v1/admin/retention-policies/{id}/preview`	GET	Dry run — shows records that would be deleted
`/api/v1/admin/retention-policies/{id}/run`	POST	Manually trigger cleanup
`/api/v1/admin/retention-policies/run-all`	POST	Run all enabled policies

Supported tables: audit_logs, usage_records, alert_history, token_blacklist, dlp_events. Retention period range: 1–3,650 days. One policy per table per tenant.

Configuration export and import

Export a complete org configuration snapshot for backup or migration:

GET /api/v1/admin/orgs/{org_id}/config/export

Schema version 2.0 covers 20 configuration domains including DLP rules, compliance bundles, policy templates, routing rules, entitlements, group configs, webhooks, alert rules, SAML configs, IP allowlists, and retention policies.

Import a configuration snapshot:

POST /api/v1/admin/orgs/{org_id}/config/import

The import operates as a diff — it adds new items, updates existing ones, and removes items not present in the snapshot. Both schema v1.0 and v2.0 are accepted. Every import is recorded in the audit trail.