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.
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.