security

Intended Documentation

Tenant Administration

Tenant-scoped admin endpoints for trust posture, environments, members, and role assignment — exact routes, request/response fields, required permissions, and failure modes.

intermediate7 min readimplemented

Tenant Administration#

Tenant administration is the read-and-govern surface for a single tenant's trust boundary. It exposes the tenant's trust overview, its environments, its members, and the ability to change a member's enterprise role. Every endpoint is tenant-scoped and permission-checked, and never returns another tenant's data.

Two tenants, each with isolated policies, Ed25519 signing keys, single-use token nonces, and a hash-chained audit log, separated by a trust boundary. A cross-tenant admin call is rejected with 403 TENANT_MISMATCH. — Tenant isolation

Authorization model#

All read endpoints on this page require the enterprise permission trust:read, which every enterprise role holds (owner, admin, operator, auditor, reviewer, read_only). Changing a member's role requires members:manage, which only owner and admin hold. See the full matrix in Roles and Token Governance.

The tenant is taken from the authenticated credential, then cross-checked against x-tenant-id and the body/query tenantId. Any disagreement (when the header is present) is rejected with 403 TENANT_MISMATCH.

Read the tenant, trust posture, and workspace#

Three read endpoints return progressively more context. All take tenantId as a query parameter and require trust:read.

GET/admin/tenantRequires auth

Returns the organization record, your resolved actor role and permissions, the tenant's environments, the trust overview, and identity readiness in a single payload.

tenantIdstring*Must match the authenticated credential and the x-tenant-id header.

GET/admin/trustRequires auth

Returns just the trust overview: active member and credential counts, open evidence-export count, 7-day emergency-event count, production environment status, open anomaly/recommendation counts, a 0–100 trustScore, and human-readable postureNotes.

tenantIdstring*Tenant identifier.

GET/admin/workspaceRequires auth

The aggregate workspace: tenant + members + role matrix + credentials + audit exports + emergency events in one response, for building an admin console view.

tenantIdstring*Tenant identifier.

bash

curl "https://api.intended.so/admin/tenant?tenantId=tenant_acme_prod" \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod"

Trust overview fields#

The overview object (also returned standalone from GET /admin/trust) contains:

Field	Type	Meaning
`activeMemberCount`	int	Active tenant members
`activeApiCredentialCount`	int	Active (non-revoked, non-expired) API credentials
`openEvidenceExportCount`	int	Evidence exports still `queued` or `processing`
`emergencyEventCount7d`	int	Emergency control events in the last 7 days
`productionEnvironmentStatus`	`active` · `halted` · `archived` · null	Status of the production environment
`openAnomalyCount` / `openRecommendationCount`	int	Open intelligence signals
`trustScore`	0–100	Heuristic posture score (lowered by a halted production env, recent emergencies, large credential footprint, and open anomalies)
`postureNotes`	string[]	Plain-language posture findings
`quickActions`	object[]	Suggested next actions, each with its `requiredPermission`

trustScore is an operational heuristic

trustScore is a tenant-local posture signal computed from the counts above. It is not a compliance attestation or a certified control score, and it does not map to SOC 2 / ISO / EU AI Act controls — the platform encodes no such control mappings.

Environments#

Environments are returned inline on GET /admin/tenant (and GET /admin/workspace) as environments[]. Each tenant is initialized with three: dev, staging, and production (the last flagged isProduction: true). Each environment record carries status (active · halted · archived), haltedAt / haltedBy (set by emergency controls), and trustNotes.

Members#

GET/admin/membersRequires auth

Lists the tenant's members with their resolved enterprise role, portal role, environment scope, status, and last-active timestamp. Requires trust:read.

tenantIdstring*Tenant identifier.

Each member record includes:

Field	Notes
`userId`, `name`, `email`	Identity of the member
`role`	Enterprise role: `owner` · `admin` · `operator` · `auditor` · `reviewer` · `read_only`
`portalRole`	The corresponding portal role
`environmentKey`	Scope of the role assignment (`global` by default)
`status`	`active`, etc.
`grantedBy`, `grantedAt`, `revokedAt`, `lastActiveAt`	Assignment provenance

Change a member's role#

POST/admin/members/:id/roleRequires auth

Assigns an enterprise role to a member. Requires members:manage (owner / admin only). Setting a global role also updates the member's portal role to the mapped equivalent.

idstring*Path parameter: the target user's id.

tenantIdstring*Body field; must match the credential and x-tenant-id.

environmentKeystringScope the assignment to a single environment instead of global.

reasonstringFree-text rationale, recorded with the assignment.

bash

curl -X POST https://api.intended.so/admin/members/user_123/role \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "role": "operator",
    "reason": "On-call rotation update"
  }'

Failure modes#

Status	Code	Cause
400	`INVALID_ADMIN_TENANT_QUERY` / `INVALID_ADMIN_MEMBERS_QUERY` / `INVALID_ADMIN_MEMBER_ROLE_REQUEST`	Missing/invalid `tenantId`, unknown `role`, or malformed body
401	`UNAUTHENTICATED_ACTOR`	No resolvable actor on the request
403	`TENANT_MISMATCH`	`x-tenant-id` ≠ query/body `tenantId`
403	`FORBIDDEN` (+ `permission: "trust:read"` or `"members:manage"`)	Role lacks the required permission
403	`ACTOR_NOT_FOUND`	Caller is not a member of the tenant and is not an API-key actor
404	`ORG_NOT_FOUND`	No organization exists for the tenant
404	`MEMBER_NOT_FOUND`	The target user id is not a member of this tenant

Tenant boundary is strict

x-tenant-id, the query/body tenantId, and the authenticated credential must all resolve to the same tenant. There is no admin path that reads or mutates another tenant's members, environments, or posture.

Tenant Administration#

Authorization model#

Read the tenant, trust posture, and workspace#

Trust overview fields#

Environments#

Members#

Change a member's role#

Failure modes#

Next Steps#