# Platform and tenant administrators (/docs/administration/administrators)









BullSequana AI has two protected administrator assignments. A **platform administrator** manages the platform: its tenants, their administrators, and the platform administrators. A **tenant administrator** manages one tenant: its members, groups, roles, service accounts, settings, and other administrators. Neither is a functional role, and neither can be granted through a custom role.

This page is for platform administrators, and for tenant administrators who appoint other administrators of their tenant. For the permissions each assignment carries, see [Administrator boundaries](/docs/reference/roles-permissions/system-roles#administrator-boundaries).

## What each assignment grants [#what-each-assignment-grants]

| Assignment             | Grants                                                                                                                                                                                                                                                                          | Does not grant                                                                                                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Platform administrator | Tenant lifecycle, deployment policies and quotas, platform administrators and every tenant's administrators, model routing, GPU usage, and the platform configuration. It includes inherited administration of the Global organization, while the person is a member of Global. | Administration of other tenants, or access to their content. A platform administrator who must administer a customer tenant also needs that tenant's membership and a tenant-administrator assignment. |
| Tenant administrator   | Administration of one tenant, while the person is a current member of it                                                                                                                                                                                                        | Platform administration, other tenants, or the AI, Data and inference functional roles. A tenant administrator who also deploys models or works with data needs those roles.                           |

An administrator assignment does not replace resource sharing. A tenant administrator does not open another member's private files, Agents, or experiments without a grant on them.

## Before you begin [#before-you-begin]

| Task                                                                 | Permission                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| List, grant, or revoke platform administrators                       | [platform.admin.list](/docs/reference/roles-permissions/platform#platformadminlist), [platform.admin.assign](/docs/reference/roles-permissions/platform#platformadminassign), [platform.admin.revoke](/docs/reference/roles-permissions/platform#platformadminrevoke)                                        |
| List, grant, or revoke the administrators of any tenant              | [platform.tenant.admin.list](/docs/reference/roles-permissions/platform#platformtenantadminlist), [platform.tenant.admin.assign](/docs/reference/roles-permissions/platform#platformtenantadminassign), [platform.tenant.admin.revoke](/docs/reference/roles-permissions/platform#platformtenantadminrevoke) |
| List, grant, or revoke the administrators of a tenant you administer | [tenant.admin.list](/docs/reference/roles-permissions/tenant#tenantadminlist), [tenant.admin.assign](/docs/reference/roles-permissions/tenant#tenantadminassign), [tenant.admin.revoke](/docs/reference/roles-permissions/tenant#tenantadminrevoke)                                                          |

Platform administrators hold the platform permissions, and tenant administrators hold the tenant permissions of their tenant. The person you appoint must already have an account. Neither flow creates an account or sends an invitation; to create a local account, see [Create a local account](/docs/administration/members#create-a-local-account).

## Platform administrators [#platform-administrators]

Open **Administration → Administrators** to see the **Platform Administrators** list. Each row shows the account, marked **You** for your own and **Disabled account** for a disabled one, and the **Revoke** action.

<img alt="Platform Administrators list with Add platform administrator, each administrator's status, and Self-removal disabled on your own row" src="__img0" />

### Add a platform administrator [#add-a-platform-administrator]

1. Select **Add platform administrator**.
2. Read the scope summary. The assignment manages the platform and administers Global. It is not limited to the tenant currently selected.
3. Under **Choose an account**, either choose a member of Global under **Global member**, or select **Find by email** and enter the exact email of an existing account, which can be outside Global.
4. Check the **Selected account**.
5. Select &#x2A;*I understand that this grants platform-wide administration, not access to just one tenant.**
6. Select **Grant platform administrator access**.

<img alt="Add platform administrator page with what the role grants, the Global member and Find by email choices, and the confirmation check box" src="__img1" />

The account is added to Global if it is not a member yet. That membership remains if the grant fails, and also after the platform administration is later revoked.

### Revoke a platform administrator [#revoke-a-platform-administrator]

Select **Revoke** on the person's row and confirm. Revocation removes platform administration only. The person keeps their Global membership, the tenant-administrator assignments they hold independently, and their content.

A protected row shows why in place of **Revoke**:

* **Self-removal disabled**: you cannot revoke your own assignment.
* **Last enabled administrator**: the platform keeps one enabled platform administrator. Add another one first.
* **Revocation pending**: a revocation is still being synchronized.

## Assign tenant administrators [#assign-tenant-administrators]

Open **Administration → Tenants**, select the tenant, then open its **Administrators** tab. The **Tenant Administrators** list shows each administrator with their assignment:

<img alt="A tenant's Administrators tab with each administrator's Direct assignment, status, and Revoke" src="__img2" />

* **Direct**: a tenant-administrator assignment for this tenant. It can be revoked here.
* **Inherited**: administration that comes from platform administration, for the Global organization. It shows **Managed at platform level** and is changed under **Administration → Administrators**.

A tenant's administrators become available once its organization has been created. You assign them without joining the tenant yourself, and the assignment gives you no access to the tenant's content or its other settings.

### Add a tenant administrator [#add-a-tenant-administrator]

1. On the **Administrators** tab, select **Add administrator**.
2. Read what the role allows: **Manage settings**, **Manage members**, and **Manage administrators** of the tenant. Choose someone you trust to manage access for others.
3. Choose the person. Under **Members**, select a current member of the tenant. Or select **Find by email**, enter the exact email of an existing account, which can be outside the tenant, and select **Find account**.
4. For a person who is not a member yet, select **Also add this person as a member of** the tenant. They remain a member if the grant fails or their administrator access is later removed.
5. Select **I understand that this person will have administrator access to** the tenant.
6. Select **Grant administrator access**.

### Revoke a tenant administrator [#revoke-a-tenant-administrator]

Select **Revoke** on the person's row and confirm. Revocation removes the direct tenant-administrator assignment only. Their ordinary membership, their content, and any inherited Global authority remain.

A tenant always keeps one administrator: the last one cannot be revoked. Add another administrator before revoking this one.

## How assignments take effect [#how-assignments-take-effect]

Each assignment is a membership of a protected Keycloak group:

| Assignment             | Keycloak group                                                                                                                     |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Platform administrator | The top-level realm group `platform-administrators`                                                                                |
| Tenant administrator   | The `tenant-administrators` group inside the tenant's Keycloak Organization, together with current membership of that Organization |

The platform bootstrap creates `platform-administrators` and the groups of the Organizations it declares, and the tenant operator creates `tenant-administrators` for each tenant it provisions. The BSQAI API recognizes these groups by their management attributes, not by their names: `bsqai.identity.managed-by`, `bsqai.identity.role` set to `platform.admin` or `tenant.admin`, and, for a tenant group, `bsqai.identity.organization-id` set to the tenant's Organization UUID. A newly provisioned tenant's group is empty until someone is assigned.

A synchronization worker projects these memberships into the platform's authorization store about every 30 seconds. Failures of the worker can extend the delay. Until it has run, the lists show that synchronization may still be pending, and a tenant's **Administrators** tab shows the person as **Inactive** instead of **Active**.

Keep these rules when you work with the groups:

* Use the Portal flows, or the [administrator API](#administrator-api), to change assignments. They apply the safeguards on this page, and the platform-administrator grant also adds Global membership.
* Do not rename a group or create a lookalike group: a group without the management attributes grants nothing.
* Do not attach Keycloak realm or client roles to these groups.
* Do not grant broad Keycloak realm-management roles, or edit authorization records directly, to work around missing access.
* OIDC group synchronization cannot target these groups; see [Synchronize OIDC groups](/docs/administration/enterprise-login#synchronize-oidc-groups).

Keep a working Keycloak administrative recovery login for the case where no platform administrator can sign in.

## Verify an assignment [#verify-an-assignment]

1. Wait until the list no longer shows that synchronization may be pending. On a tenant's **Administrators** tab, the person then shows **Active**.
2. Ask the person to sign out of the Portal and sign in again. Signing in again does not replace a failed synchronization.
3. Check what they can do:
   * A platform administrator sees the Platform group of **Administration** and Global's tenant settings.
   * A tenant administrator manages their tenant, but sees no platform pages and no other tenant's settings.
   * Ordinary members keep their OmniChat access without administrative controls.

If access is missing, check that the account is enabled and a member of the Organization, that the group has the management attributes, and the errors of the Keycloak synchronization worker.

## Administrator API [#administrator-api]

Platform routes take the tenant's organization ID in the path. Tenant routes act on the tenant sent in `X-Tenant-Id`. Grants and revocations return `202 Accepted`; the change takes effect after synchronization.

| Route                                                                          | Permission                     | Does                                                         |
| ------------------------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------ |
| `GET /v1/admin/platform-administrators`                                        | `platform.admin.list`          | Lists the platform administrators                            |
| `POST /v1/admin/platform-administrators/lookup`                                | `platform.admin.assign`        | Finds an existing account by its exact `email`               |
| `PUT /v1/admin/platform-administrators/{user_id}`                              | `platform.admin.assign`        | Grants platform administration and ensures Global membership |
| `POST /v1/admin/platform-administrators/{user_id}/revoke`                      | `platform.admin.revoke`        | Revokes platform administration only                         |
| `GET /v1/admin/tenant-identities/{tenant_id}/administrators`                   | `platform.tenant.admin.list`   | Lists a tenant's administrators                              |
| `GET /v1/admin/tenant-identities/{tenant_id}/administrator-candidates`         | `platform.tenant.admin.assign` | Lists the tenant's enabled members                           |
| `POST /v1/admin/tenant-identities/{tenant_id}/member-lookup`                   | `platform.tenant.admin.assign` | Finds an existing account by `email` or `username`           |
| `PUT /v1/admin/tenant-identities/{tenant_id}/administrators/{user_id}`         | `platform.tenant.admin.assign` | Grants tenant administration                                 |
| `POST /v1/admin/tenant-identities/{tenant_id}/administrators/{user_id}/revoke` | `platform.tenant.admin.revoke` | Revokes the direct assignment                                |
| `GET /v1/tenant/identity/administrators`                                       | `tenant.admin.list`            | Lists the administrators of the selected tenant              |
| `GET /v1/tenant/identity/administrator-candidates`                             | `tenant.admin.assign`          | Lists the selected tenant's enabled members                  |
| `PUT /v1/tenant/identity/administrators/{user_id}`                             | `tenant.admin.assign`          | Grants administration of the selected tenant                 |
| `POST /v1/tenant/identity/administrators/{user_id}/revoke`                     | `tenant.admin.revoke`          | Revokes the direct assignment in the selected tenant         |

A tenant-administrator grant takes `{"ensure_membership":true}` to also add the person to the tenant. API keys cannot hold these permissions.

## Related pages [#related-pages]

* [Administration and operations](/docs/administration)
* [Manage members](/docs/administration/members)
* [Enterprise sign-in](/docs/administration/enterprise-login)
* [System roles](/docs/reference/roles-permissions/system-roles)
* [Keycloak](/docs/foundation/components/keycloak)
