Tenant scoping and tenant switching

logiccloud DELEGATE is multitenant. Every request acts in exactly one organization. This page explains how the server chooses it, why a request answers 403, and how support staff and superadmins work in a tenant that is not their own.

For the permissions of each role, see Roles and access.

How the server resolves the organization

The server checks these sources in order. The first one that names an organization wins.

1. The organization in the route, for example /organizations/{orgId}/members.
2. The x-organization-id header.
3. The open tenant switch of the caller.
4. The primary membership of the caller.

A malformed organization id in the route or the header answers 400. The query string and the request body never choose the tenant.

An API key skips steps 3 and 4. It acts in the organization it belongs to.

The 403 cases

Cause	Message or code	What to do
Tenant switch required	code: TENANT_SWITCH_REQUIRED	Open a tenant switch to the organization, then repeat the call.
Not a member	“Not a member of this organization”	Ask an admin of that organization to invite you.
Organization context required	“Organization context required”	The caller has no membership and sent no organization. Send x-organization-id.
Organization inactive	“Organization is inactive”	An administrator of the platform must enable the organization again.
Organization not found	“Organization not found”	Check the id.
API key not authorized	“API key not authorized for this organization”	A key works in its own organization only. Use a key of the target organization.
Insufficient permissions	Permission error from the endpoint	The role lacks the permission. Ask an admin to change the role.

Details for each case:

• Tenant switch required. The body is {"statusCode": 403, "code": "TENANT_SWITCH_REQUIRED", "message": "..."}. A superadmin who is not a member of the organization gets it. A user with the SUPPORT role who is not a member gets it too. A switch to organization X does not open organization Y.
• Not a member. The caller is not a member and does not hold the SUPPORT role. The check for SUPPORT is live. The server never caches it, so removing the role takes effect on the next request.
• Organization context required. No source named an organization, and the caller is not a superadmin. A superadmin without any organization context may still call endpoints that need none.
• Organization inactive or not found. The organization is disabled, or the id does not exist. A superadmin who names the organization in the route may still manage a disabled organization.
• API key not authorized. The key belongs to another organization than the one the request names. An API key never takes the superadmin or SUPPORT path. Every /api/v1/tenant/* switch endpoint also answers 403 to an API key.
• Insufficient permissions. The caller is a member, but the role lacks the permission the endpoint needs. The audit log, for example, needs audit:read, which only admins hold.

Platform endpoints do not act inside one tenant. These are the organization management of superadmins, the tenant switch endpoints and the platform reports. They answer neither TENANT_SWITCH_REQUIRED nor “Not a member”.

The tenant switch

A tenant switch is a time-limited, audited permission to act in a tenant that you are not a member of. Only superadmins and users with the SUPPORT role can open one. API keys never can.

Start

POST /api/v1/tenant/switch with this body:

{
  "organizationId": "<uuid>",
  "reason": "Customer ticket 4711: check the egress rules",
  "expiresInMinutes": 60
}

• reason has 3 to 500 characters. It is required for a target you are not a member of.
• expiresInMinutes has a range of 1 to 4320 (72 hours). The default is 480 (8 hours).
• The answer is 201 with the switch, including switchedAt and expiresAt.
• If you are a member of the target, the call answers 204. Any open switch ends and you work in your own tenant again.
• Only one switch is open per user. A new switch replaces the old one.

Extend

POST /api/v1/tenant/switch/extend needs a reason. The optional expiresInMinutes counts from now. A switch never ends later than 72 hours after its start, and an extension never shortens it. When the switch cannot grow any more, the call answers 400.

End

DELETE /api/v1/tenant/switch ends the open switch. The query parameter trigger is user (default) or logout. The server also ends a switch for these reasons:

Trigger	Cause
user	You ended the switch.
logout	You signed out. The web UI sends this trigger.
home	You switched to a tenant you are a member of.
replaced	You opened a new switch.
expired	The expiry passed. A sweep runs every 5 minutes.
revoked	The SUPERUSER or SUPPORT role of the user was revoked.

An expired switch stops working at once. The sweep only writes the end record.

Audit

Every start, extension and end writes one audit row in the target tenant. The row names the person, the reason and the trigger. Admins of the target tenant can read it in the audit log.

SUPPORT staff inside a switch

A user with the SUPPORT role holds no membership in the customer tenant. Inside an open switch, the user gets the admin permission set of that tenant. Outside a switch, the user gets 403 TENANT_SWITCH_REQUIRED.

GET /api/v1/me/permissions shows this state: supportAccess is true and roleName is null.

API keys never switch

An API key is bound to one organization. It cannot open, extend or end a switch, and it cannot act in another organization. It never has more permissions than the person who created it. See Roles and access.