Move a device between organizations

One machine can belong to more than one organization and move between them with one command. The sxaccess tenant commands do that, and they are not the same thing as identities.

A contractor's laptop, a shared build machine, an engineer who works across two companies: one device, more than one organization. sxaccess tenant is how the CLI moves that device between them. Each organization the device joins this way gets an enrolment of its own, kept on the device, so moving back later is one command rather than a fresh join. Create and switch organizations has the short version, next to how the dashboard and the apps switch.

One rule makes the rest of this page make sense: while an organization is active, its enrolment is the one the agent uses. The agent loads the active organization's configuration instead of the identity's - at startup, when signing in, when connecting, and when an identity is switched. Settings are the exception: the flags you give sxaccess start are saved with the identity, so they do not apply while an organization is active.

Join a second organization and move between them

1
Start with no argument the first time
The device only knows the organizations it has been shown. Say you enrolled it into acme-corp by signing in while your account belonged to acme-corp only, and you have since been added to acme-labs. The list is empty, so the first move is switch with no argument. (Had your account belonged to several organizations when you enrolled, start would have asked you to pick one then, and sxaccess tenant list would already show them all.)

switch signs you in - reusing a recent sign-in if the agent still has one, otherwise opening a browser - and then asks which organization to join. Signing in disconnects the device, so it stays offline until the switch is done.
shell
```
sxaccess tenant switch
```
2
Pick from the list it prints
You get a numbered list and the prompt Enter choice: even when your account belongs to only one organization - the heading says multiple organizations either way. Type the number. Anything that is not a listed number ends the command with invalid organization selection and what you typed; nothing is joined, and the device stays disconnected until you run sxaccess start or the switch again.

The device is enrolled into the organization you picked and then connected, so this one command takes you from signed out to on the network.
shell
```
You belong to multiple organizations. Select the one to enroll this device into:  1) acme-corp  2) acme-labsEnter choice: 2Switched to organization "acme-labs".
```
3
Check what the device now knows
list runs locally and costs nothing. * marks the active organization. ✓ marks every organization the device holds an enrolment of its own for: switching back to one of those signs in with the device's key, with no browser. The mark appears as soon as a join starts, though, so a first join that failed or was abandoned shows it too.

An organization with no ✓ has not been joined this way. Here that includes acme-corp, where the device was enrolled before your first switch: that enrolment belongs to the identity, not to this list.
shell
```
$ sxaccess tenant listYour organizations (* = active, ✓ = joined on this device):      acme-corp (d3h0k2ss5ltc73a9h6v0) * ✓  acme-labs (d3h1a8ss5ltc73a9h6vg)Switch with: sxaccess tenant switch <name>
```
4
Switch by name
Give switch a name or an ID from list; names match without regard to case. It disconnects, activates that organization, signs in and connects again. For an organization marked ✓, it signs in with the device's key, with no browser and no prompt.

Here acme-corp has no ✓, so this switch is a first join. Read the note after these steps before you run it.
shell
```
$ sxaccess tenant switch acme-corpSwitched to organization acme-corp
```
5
Confirm which one is active
current prints the active organization and its ID. Read it for what it is: the agent's record of which organization is selected, not proof that the connection is up. For that, use sxaccess info - and see the note below on what info does not tell you.
shell
```
$ sxaccess tenant currentacme-corp (d3h0k2ss5ltc73a9h6v0)
```

The commands

All of them talk to the agent, so it has to be running. None takes flags of its own, and none reads SX_ environment variables.

Command	What it does
`sxaccess tenant list`	Every organization this device knows about, with the active one and the joined ones marked. A device that has never been shown any answers `No organizations known yet. Run 'sxaccess tenant switch' to log in and pick one.`
`sxaccess tenant current`	The active organization and its ID. While the device still uses the enrolment of its identity, it answers `No active organization.` - see the warning below
`sxaccess tenant switch`	With no argument: sign in, list the organizations your account belongs to, ask which one, join it and connect
`sxaccess tenant switch <name>`	With an argument: match it against the known organizations by name, ignoring case, or by ID. Disconnect, activate, sign in, connect

Choosing the organization when you enrol

When your account belongs to several organizations, sxaccess start and sxaccess enroll ask which one to join after the browser sign-in, with the same numbered list. To answer in advance, give the organization's ID: sxaccess start --tenant d3h0k2ss5ltc73a9h6v0. The ID is the value in brackets in sxaccess tenant list, and the id that GET /api/organizations returns in the Public API.

--tenant is ignored with an enrollment key, which always enrols the device into the key's organization. It also only counts when the device enrols: a device that is already enrolled keeps its organization, and on a connected one start prints This device is already connected and changes nothing. To move such a device, use sxaccess tenant switch. An enrolment made with --tenant belongs to the identity, like one made with a key: sxaccess tenant list and sxaccess tenant current do not show it, and the first switch leaves it behind.

This is not the same as an identity

The two look alike from the outside, and their scope is different.

An identity is one saved sign-in on this machine: its own key, its own settings, its own enrolment. You create it with sxaccess identity add; it means nothing to the server. Use identities to keep separate sign-ins side by side on one machine - two accounts, or an install driven by a different enrollment key.

An organization - what the sxaccess tenant commands are named after - is one your account is a member of. The list comes from the server, not from you, and joining one enrols the device there.

So reach for sxaccess tenant to move between organizations you belong to, and for identities only to keep separate sign-ins apart. Where both are set, the organization's enrolment is the one in force.

Three things these commands do not do

They do not leave an organization. There is no command to undo a join. The enrolment stays on the device, and the device stays listed in that organization's dashboard until someone removes it there - see Devices, or offboarding when the person is leaving too.

They do not join unattended. The no-argument form reads your answer from the terminal, a first join may open a browser, and the --no-browser flag of start and enroll does not exist here. Switching by name to an organization with a ✓ is the exception: it needs no browser and no answer. On a machine nobody is sitting at, enrol with an enrollment key instead.

They do not change what info reports. Switching organization leaves the identity untouched, so sxaccess info -d goes on naming the identity on its Identity row and never names the organization. Use sxaccess tenant current for that question and info for the connection.

Create and switch organizationsOrganizations in the dashboard and the apps: creating one and moving between them.Read more What the agent has storedThe record of system changes the agent keeps, and how to clear it safely.Read more Enrollment keysHow a machine with nobody at it joins an organization.Read more DevicesRemoving a device from an organization, from the other side.Read more

Move a device between organizations

Join a second organization and move between them

The commands

Choosing the organization when you enrol

This is not the same as an identity

Related