Skip to content

Root Membership Exclusive

URI: https://docs.ankatech.co/errors/root-membership-exclusive
HTTP Status: 409 Conflict

When you see this

A person is one identity holding a membership in each tenant they belong to. The membership of the platform tenant (ROOT) is exclusive in both directions:

  • an identity that is a platform administrator (it holds the ROOT membership) can never be a member of a tenant — a platform administrator reaches a tenant only through consented, audited support access (impersonation);
  • an identity that is a member of a tenant can never be given the ROOT membership.

The request would have created a membership that breaks that rule, so it was refused before anything was written. The same answer is given when the database itself refuses a concurrent writer: the rule is a foreign key on the membership table, not only a check in the service.

Common Causes

  • Adding a platform administrator's email to a tenant — createHumanUser (POST /api/v3/admin/tenants/{tenantId}/users) with an address that belongs to a platform administrator.
  • Provisioning a tenant whose first administrator is a platform administrator — the administrator email of a tenant provisioning names a platform identity.
  • Appointing a platform administrator as a tenant administrator.
  • Adding a tenant member to the platform tenant.

Response Example

{
  "type": "https://docs.ankatech.co/errors/root-membership-exclusive",
  "title": "Root Membership Exclusive",
  "status": 409,
  "detail": "A platform identity cannot be a member of a tenant, and an identity that is a member of a tenant cannot be a member of the platform tenant.",
  "instance": "/api/v3/admin/tenants/3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f0b1c34/users",
  "timestamp": 1789041600,
  "extensions": {
    "requestId": "3f1c2a9e-4b7d-4e2a-9c11-0a2b3c4d5e6f"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The detail is one fixed sentence for every refused request: it names the rule and never the address, the identity or a tenant.

How to Resolve

  1. Do not retry: the refusal holds as long as the identity holds its current membership.
  2. To work inside a tenant as a platform administrator, use support access: the tenant grants consent and the platform administrator opens an impersonation session, which is audited in that tenant.
  3. To give a person both roles, use two identities with two distinct email addresses — one platform administrator and one tenant member.

Nothing was changed by the refused request: no identity, membership, role or invitation was written, and no link was sent.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.