# Organizations, locations, and access Viam organizes your machines into a three-level hierarchy: organizations contain locations, and locations contain machines. This hierarchy is also the foundation for access control. You grant permissions at any level, and they apply to everything within that level. ## Organization, location, and machine hierarchy **Organizations** are the top-level grouping. An organization typically represents a company or team. Each organization has its own members, API keys, billing, and data region. **Locations** group machines within an organization. A location can represent a physical site, a project, or any logical grouping that makes sense for your fleet. You can nest locations up to three levels deep to create sub-groupings. **Machines** are individual devices running `viam-server`. Each machine belongs to exactly one location. ### How the hierarchy affects access When you grant a user or API key access at a given level, the permissions apply to everything below it: - **Organization-level access** grants access to all locations and machines in the organization. - **Location-level access** grants access to all machines in that location and its sub-locations. - **Machine-level access** grants access to only that specific machine. This means you can use the hierarchy to approximate team boundaries even without an explicit team or group feature. For example, create a “Production” location and a “Testing” location, then grant field operators access only to “Production.” For details on what each role can do, see [Permissions](https://docs.viam.com/organization/rbac/). ### Choose your structure Before connecting devices, decide how you want to group your machines: - **By physical site**: one location per office, warehouse, or deployment site. - **By project or environment**: locations for “Production,” “Staging,” and “Development.” - **By customer**: if you deploy machines to customers, one location per customer lets you share access with that customer’s organization. You can combine these approaches using nested locations. For example, a “Chicago warehouse” location could contain “Floor 1” and “Floor 2” sub-locations. ## Create and manage organizations ### Create an organization 1. Log into [the Viam app](https://app.viam.com/). 2. Click the organization dropdown in the top navigation bar and click the **+** button. 3. Name the organization. 4. From the **Data region** dropdown, choose where Viam should store your data. See [Choose data region](https://docs.viam.com/organization/data-regions/). 5. Click **Create**. ### Rename an organization You must be an organization owner. 1. Click the organization name in the top navigation bar and click **Settings**. 2. In the **Details** section, change the name and click **Rename**. #### Caution If your organization owns modules or packages in the Viam Registry, the namespace changes automatically. You must update any configurations that reference your modules using the old namespace. ### Delete an organization 1. Delete all locations in the organization. 2. Click the organization name in the top navigation bar and click **Settings**. 3. At the bottom of the page, click **Delete organization**. ## Create and manage locations ### Create a location 1. Click the organization name in the top navigation bar and click **Locations**. A default location called `First Location` is created automatically for new organizations. Use the **…** menu to rename it. 2. To create additional locations, click **\+ Add location**. ### Create sub-locations 1. Create a new location using **\+ Add location**. 2. On the new location’s page, click the **…** menu and click **Move**. 3. Choose a parent location. You can nest locations up to three levels deep. ### Move a machine to a different location Organization owners and location owners can move machines between locations. 1. Navigate to your machine’s page. 2. Click the **…** button in the upper-right corner. 3. Select **Move to a new location**. 4. Choose the destination location and confirm. #### Important Moving a machine changes its network address and its access permissions. Users with access to the old location lose access, and users with access to the new location gain access. Historical data stays associated with the original location. ### Share a location with another organization To give another organization access to a location, see [Share a location with an organization](https://docs.viam.com/organization/access/#share-a-location-with-an-organization). ## Your account ### Create an account and log in Navigate to [app.viam.com](https://app.viam.com/). Click **Sign Up** to create an account using Google, GitHub, Apple, or email. If you already have an account, click **Log In**. To reset a forgotten password, click **Forgot password** on the login page. #### Note Accounts created from different authentication providers (for example, Google and email) are separate accounts, even if they use the same email address. ### Sign out Click your profile icon in the upper-right corner and click **Sign out**. ### Delete your account Contact [contact@viam.com](mailto:contact@viam.com) to delete your account. Account deletion may result in destruction of associated content. ### CLI authentication You can authenticate with the Viam CLI using either interactive login or an API key: ```sh viam login ``` ```sh viam login api-key --key-id --key ``` To check who you are currently authenticated as: ```sh viam whoami ``` If you work with multiple organizations or API keys, you can set up CLI profiles to switch between credentials: ```sh viam profiles add --profile-name production --key-id --key ``` ```sh viam profiles list ``` You can also set default org and location for CLI commands: ```sh viam defaults set-org --org-id ``` ```sh viam defaults set-location --location-id ``` For the full CLI reference, see [CLI](https://docs.viam.com/cli/reference/). ## FAQ ### Can I move a location to a different organization? No. You can [share a location](https://docs.viam.com/organization/access/#share-a-location-with-an-organization) with another organization, but the location stays in its original organization. Machines in a shared location continue to use the primary organization for data association, private ML models, and registry items. ### Can I rename my organization after creation? Yes, if you are an organization owner. See [Rename an organization](https://docs.viam.com/organization/overview/#rename-an-organization). ### Can I move a machine across organizations? No. You can only move a machine to a different location within the same organization. To transfer a machine to another organization, you would need to set up a new machine in the target organization and reconfigure it. ## Next steps - [Control access](https://docs.viam.com/organization/access/) to your machines by granting and revoking permissions. - [Manage API keys](https://docs.viam.com/organization/api-keys/) for programmatic and CLI access. - Review the [permissions reference](https://docs.viam.com/organization/rbac/) to understand what each role can do.