Organizations and Environments
Organizations and environments define the two primary scopes in the AISIX Cloud control plane. The organization establishes ownership and shared administration. The environment establishes which AISIX gateways receive projected configuration.
This separation keeps account administration separate from traffic behavior. Members, teams, and provider credentials belong to the organization. Models, caller API keys, policies, and cache policies belong to the environment that serves traffic.
For live traffic, the environment is usually the scope that matters first. A saved environment resource affects live traffic only when it belongs to the environment attached to the target AISIX gateway.
Members, teams, shared administration, and provider credentials.
Scope Model
The AISIX Cloud control plane can manage more than one gateway and more than one set of gateway resources. Organizations and environments make it clear which team owns the deployment and which AISIX gateway receives each environment-scoped resource.
Organization Scope
An organization is the top-level ownership boundary. It is the scope for members, teams, shared administration, and provider credentials.
An On-Premises control plane starts with one organization, Default, created together with the first administrator. Rename it in the organization settings. Nobody can create further organizations on an On-Premises control plane, from the dashboard or the API. A control plane upgraded from 1.5.x or earlier can still hold several, and its console is blocked until they are consolidated into one. An account that belongs to no organization sees a message to contact an administrator, who can invite it into one.
Use organization scope to reason about account ownership and shared administration. It is usually not the first scope to check when a saved gateway resource does not affect live traffic.
Environment Scope
An environment is the unit that groups gateway resources and projects them to the attached AISIX gateway or gateways.
Environment scope turns saved control-plane state into live gateway behavior. A resource can exist in the control plane and still not affect the gateway you are testing if it belongs to another environment.
When a resource does not affect traffic as expected, confirm first that the resource belongs to the same environment as the target AISIX gateway. For provider keys, also confirm that the provider key is allowed in that environment.
Create or Select an Environment
Open Environments in the dashboard.
To create an environment, select New environment, enter a display name, and select Create environment. The confirmation shows the environment ID and links to its Data planes view. Copy the ID for provider setup examples, which use it as ENV_ID.
To use an existing environment, select it from the environment list. The environment ID appears below its display name.
Rename an Environment
Select the pencil next to an environment in the list, type the new name, and save. Names are unique within the organization, so a name another environment already uses is rejected.
The environment ID does not change, and neither does anything the gateway is serving. Attached AISIX gateways identify their environment by ID, so a rename is a control-plane label change only — running data planes are not reconfigured and no traffic is interrupted. Scripts and setup examples that reference ENV_ID keep working.
A member whose access comes from an environment-scoped role binding cannot rename the environment. Renaming requires write access to environments at the organization level, the same permission that creates and deletes them.
Delete an Environment
Before deleting an environment, move traffic away from every attached AISIX gateway, then stop those gateways. Deleting the control-plane environment does not drain gateway traffic.
Deleting an environment is irreversible. It removes its models, caller API keys, policies, gateway registrations, and other environment-scoped records.
Open Environments, select the delete action for the environment, and review the confirmation. Type the environment's display name, then select Delete.
AISIX Cloud revokes the environment's active gateway certificates before deleting its records. If that step fails, the environment and its resources remain in place so the deletion can be retried.
Deleting the environment also withdraws its configuration from the control plane shortly afterwards, so a gateway that is still connected stops serving that environment's configuration rather than keeping the last configuration it received. Configuration left behind by environments deleted on an earlier control-plane version is removed automatically after the control plane is upgraded.
Console Language
The dashboard and the emails the control plane sends are available in English and Chinese. Up to four settings can name a language, and the first one that names English or Chinese wins: the language picker, the organization's language, the browser's language, and the deployment default.
Language Picker
The language picker is in the top-right corner of the sign-in pages: sign-in, sign-up, forgot, reset, and set password, the single sign-on pages, organization selection, change password, and organization consolidation. It is also on the invitation page, and, once you are signed in, in the top bar to the left of the organization switcher.
Its options are Automatic, English, and 中文. The choice is kept in the browser where you make it, so it does not follow your account to another browser or device. Automatic clears the choice.
Organization Language
Open Settings and find the Language card. In Organization language, pick one of the following, then select Save changes:
- Not set: each browser's language applies, otherwise the deployment default. The option names the default currently in effect.
- English.
- 中文.
Owners and admins can change the setting. Other members see it read-only.
How the Language Is Chosen
Each kind of page checks the settings in its own order:
- Pages inside an organization: the picker, then the current organization's language, then the browser's language, then the deployment default. On the SaaS service, switching to another organization switches the dashboard to that organization's language unless the picker has a choice.
- Pages opened from an email link (accepting an invitation, setting a password, connecting a single sign-on account): the picker, then the language of the organization the link belongs to, then the browser's language, then the deployment default.
- Pages that belong to no organization (sign-in, sign-up, the password pages, organization selection): the picker, then, On-Premises only, the language of the deployment's single organization, then the browser's language, then the deployment default.
- Emails you request from your own browser: email verification and forgot password follow the picker, then, On-Premises only, the single organization's language, then the browser's language, then the deployment default. A single sign-on account claim email checks the claim's organization right after the picker.
- Emails an admin sends to someone else (member invitations, and set or reset password links): the organization's language, then the deployment default. The picker and browser language of the admin who sends them play no part.
The browser's language is read in the browser's order of preference. The first language whose primary tag is en or zh wins, so zh-CN, zh-TW, and zh-Hans count as Chinese and en-US as English. Other languages are skipped. When no setting names English or Chinese, English is used.
On-Premises, the deployment default is ui.defaultLocale in Helm; see Dashboard Language.
The deployment default used to fix the language of the whole dashboard and of every email. It is now only the fallback, and the browser's language comes before it, so a deployment with ui.defaultLocale: zh shows English to members whose browser prefers English, and the other way round. To give one organization a single language, set its language in Settings: the organization's language comes before the browser's language.
Delete an Organization
An organization owner can delete the organization and everything in it. Deletion cannot be undone.
Deleting an organization removes its environments with their models, caller API keys, policies, and gateway registrations, and also its members' memberships, teams, provider keys, MCP servers, A2A agents, invitations, admin tokens, notification channels, custom roles, and usage and audit records. Every gateway connected to one of its environments is cut off: its certificate is revoked, and it can no longer fetch configuration from the control plane.
Access ends as soon as the deletion is confirmed: the organization disappears from every member's organization list, its members, invitations, admin tokens, single sign-on connections with the account links they made, and, on the SaaS service, its domains are removed, and its environments are deleted with their gateway certificates revoked. The organization's stored data, such as usage records, audit logs, and notification deliveries, is then removed in the background, which can take a while for a large organization. The organization's slug stays reserved until that removal finishes, so a new organization cannot use the same slug before then.
Member accounts with a password are kept. People lose only their membership in the deleted organization and can still sign in to any other organization they belong to. An account without a password that belongs to no other organization is deleted with the organization, the same as when that member is removed on their own. This covers members created directly, provisioned through SCIM, or created by single sign-on on their first sign-in, and frees their email addresses.
Before deleting, move traffic away from the organization's gateways and stop them, as you would before deleting an environment. If you might need the organization's configuration again, export a backup first.
- Sign in as an owner of the organization and open Settings.
- In the Delete organization card, review what the deletion removes and select Delete organization.
- Type the organization's name to confirm, then confirm the deletion.
Afterwards, the dashboard switches to another organization you belong to, or tells you that your account belongs to none.
Only an owner can delete an organization; any other member receives 403. On an On-Premises control plane, the deployment's only organization cannot be deleted: the button is disabled with the reason, and the API returns 409 LAST_ORGANIZATION.
Next Steps
Continue with Admin Tokens to create the organization-scoped credential used by the provider setup examples. After creating a token, connect an AISIX gateway to the environment that should receive the configuration.
To back up, migrate, or reproduce an existing organization, see Organization Backup and Restore.