Join a team with a code

An invite code is a one-time code that invites whoever holds it into a team. Someone who may invite makes it on their own device and gives it to the person: as text, as a link, or as a QR code to scan. The person enters it under Join a team, sees the team before joining, and joins. Nobody gets anything until someone on the team lets them in.

A code is an alternative to an invitation by email. It differs in two ways:

It is not tied to an address. Whoever uses it first is the one who joins, with the ZestSSH account they are signed in to.
There are no fingerprints to compare. The code checks both sides’ keys, so letting the person in needs no call to read words aloud. See What the code proves.

Make a code

You can make a code if you are an owner or an admin, or if your role has Invite people into roles below theirs.

Open the team’s Team pages and choose Invite people on Overview or Members. On a phone, use the invite button on Overview, or open Members and choose Invite someone under Invitations.
The dialog Invite to Example Ops offers two ways. Choose Code or QR: “Copy, paste or scan. Works once.”
ZestSSH makes the code at once, with the first role on offer. The line at the top says what the person gets, for example “Joins as Member · Shared: Use · no end date”. To change it, choose Change. In What they get, pick the Role, a level for each vault under Vaults, and when Access ends (Never, or Pick a date), then choose Save.
Under How long it works, pick 1 hour, 1 day, 7 days or 30 days. A new code starts at 1 hour. The card says when it ends, for example “Ends at 4:00 PM”.
Give the code to the person. Choose Copy code or Copy link, or let them scan the QR code with ZestSSH on their phone (“Scan with the ZestSSH app”).

The code looks like ZEST-XXXX-XXXX-XXXX-XXXX-XXXX. The link has the code after a #: https://zestssh.com/join# and the code. A browser never sends the part after # to a website. An invite code is not a redeem code: a redeem code, which unlocks a plan or gives a team seats, has three groups after ZEST- (ZEST-XXXX-XXXX-XXXX; older ones have two), and your recovery key, though it has the same shape as an invite code, only opens your synced data.

What the card also says:

Works once. The first account that uses it uses it up.
“Holds a seat while it waits.” With the count, for example “Holds a seat while it waits. 4 of 6 seats in use.” If every seat is taken, no code is made, and the dialog says how many seats you need. See When seats run out.
The footnote: “The code checks both sides’ keys, so there’s no fingerprint comparison. ZestSSH Cloud never sees the code. You still approve who joins before they get anything.”

While recording mode is on, the code, its link and its QR code are hidden, and Show reveals them. See Recording mode.

Change or cancel a code

How long it works can be changed while the code waits.
Changing what they get makes a new code. The offer is part of what the code checks, so ZestSSH cancels the old code and makes a new one: “A new code replaces the old one, which no longer works.”
Cancel code in the dialog, or on the code’s row under Invited on the Members page, stops it at once: “Code cancelled. It no longer works.” Its seat opens up again.

You can close the dialog with Done while the code waits: “You can close this. Whoever uses it shows up under Needs attention for you to let in.” While the dialog stays open, it shows who used the code as soon as they do.

On the Members page, a waiting code is listed under Invited as Invite code, with its role and a line such as “Made by alex@example.com · ends” and the date.

Send a code instead of an email invitation

An email invitation that nobody has accepted yet has Send a code instead next to it under Invited. It opens the code with that invitation’s offer. The email invitation keeps its seat until the code is used, and then goes.

Join with a code

Open the space switcher and choose Join a team. On a computer, the switcher is in the bar at the top of the window. On a phone, tap the name at the top of the Hosts tab.
Type or paste the code, or its link, under Invite code: “Spaces, dashes and small letters are fine.” On a phone, you can choose Scan a QR code and point the camera at the QR code on their screen.
Choose Continue.

Not signed in yet? Join a team says “Joining a team needs a ZestSSH account. It’s free.” and “Your code is kept.” Sign in, or create an account, right there: on Windows and Linux with Sign in or Create an account (your browser opens zestssh.com, then brings you back), on a Mac, iPhone, iPad or Android phone with Apple, Google or an email. Once you are signed in, ZestSSH checks the code and shows the team by itself. Create a team asks you to sign in the same way.

No ZestSSH yet

Open the invite link in a browser: the page at zestssh.com/join shows the code and takes you through it, Get ZestSSH for your device, Open in ZestSSH, then sign in or create your account when the app asks. The code never leaves your browser and your device.

A zestssh://join link opens Join a team with the code typed in: “A link opened this. Nothing happens until you continue.”

Before anything is shown, your device checks what ZestSSH Cloud sent against the code. Only then do you see the team:

its name, and Invited by with who made the code;
You join as, the role;
You get, each vault with its level, or No vaults yet;
Access ends, if your access would end;
Your account, the account you are joining with;
a green line, for example “Checked with the code: this is the real Example Ops.”

It also says what the team records about how members use it, and if the team’s rules ask for something you do not have yet, such as two-step sign-in: “This team asks for two-step sign-in first. Fix that, then accept.”

Choose Join Example Ops, or Not now.

Joining needs your team keys on this device. If they are not there, ZestSSH makes them, or says what stands in the way. See Your team keys.

After you join, ZestSSH shows Waiting to be let in: “You used the code. alex@example.com lets you in from their side, and the team shows up here once they do.” Nothing of the team is on your device until then. Your app keeps a line open to ZestSSH Cloud, so the team arrives as soon as you are let in.

When a code does not work

Message	What to do
”That is not an invite code. A code looks like ZEST-XXXX-XXXX-XXXX-XXXX-XXXX.”	Check what you typed or pasted.
”This code does not work. It may have been used already, cancelled, or run out. Ask for a new one.”	Ask the person who gave it to you for a new code.
”This code does not check out. What ZestSSH Cloud sent is not what the code was made for, so nothing was joined. Ask for a new code, and tell whoever made it.”	Nothing was joined. Ask for a new code, and tell its maker.
”This team takes people from outside its own domains only with a code an owner made. Ask an owner for one.”	Your address is outside the team’s proven domains. See Guests.
”This team takes people from outside its own domains only for a set time. Ask for a code with an end date.”	Ask for a code whose access has an end date.

Tries that find no code count against a limit: 10 an hour for each account, and 30 an hour from one network address. Past it, ZestSSH says “That’s a lot of invitations for one hour. Try again later.”

Let them in

When someone uses your code, the team shows it to those who may invite:

On the Overview, under Needs attention: “sam used your invite code”, with their address, the device, the role they would get and when. It has Turn away and Review.
On the Members page, at the top, a banner: “sam used your invite code”, with Review; with several people waiting, how many, and Review opens the first. Under Waiting for you: their address and role, “Used your invite code”, the device and when, and a pill: Keys checked, or Compare fingerprints. The Members page reads who is waiting again when it opens and every 30 seconds while it is open.
On the Seats page: “Waiting for you”, where Review opens their review on the Members page.

Review opens the review: beside the list on a computer, as a dialog on a phone. It says:

“sam@example.com wants to join”, and how they signed in, for example with Google or with company sign-in.
Keys checked by your invite code: “You made” the code, shown by its first characters. “It is used up now, so nobody else can try it.”
Device: the platform they used the code on, the app (for example “ZestSSH for Android”), and when they Used the code.
They get: the role, the level in each vault, and when access ends.
Seat: “Already held by the code.”
“Not who you expected? Turn them away. Nothing has been shared with them, and the seat opens up again.”

Choose Let sam in, or Turn away. Letting someone in needs a sign-in from the last 10 minutes: if Confirm it’s you appears, sign in again. ZestSSH then says “sam@example.com is a member now.” and they get the keys of the team and of the vaults offered, sealed to the keys the code checked.

Turn away withdraws the invitation: “sam@example.com was turned away.” Nothing was shared with them, and the seat is free again.

When the keys are not checked

Only a device of the account that made the code can check the person’s keys, since only that account can open the code. On any other device, and whenever something does not match, the review says Keys not checked by a code: “This device could not check their keys with the code: it was made on another device, or something does not match. Compare fingerprints with them before you let them in.” Let sam in then asks you to compare fingerprints first, as for an email invitation. See Compare fingerprints and add them.

What the code proves

When someone joins, their keys reach the team through ZestSSH Cloud. With an email invitation, comparing fingerprints on a call is what proves the keys are really theirs. With a code, the code does that work:

Your device checks the team. The code’s maker attaches a check, made with a key derived from the code, over the team, the invitation, the maker’s own public keys and the offer (role, vaults and end date). The person’s device checks it before it shows anything as the team’s. So a server cannot show another team, another maker’s keys or another offer.
The maker’s device checks the person. The person’s device answers with a check, made with the same key, over the same team and invitation, the maker’s keys and their own public keys. The maker’s device checks it before it lets them in. So a server cannot pass off other keys as theirs. This check takes the place of comparing fingerprints.
ZestSSH Cloud never sees the code. It is given only a lookup id derived from the code to find the invitation by, the two checks, and two sealed parts: what the person is shown (the team’s name, the role and the vaults), sealed under a key derived from the code, and the code itself, sealed to the maker’s own account key so that the maker’s other devices can check the person too.

Anyone who holds the code before the person uses it can use it instead. Give it the way you would give a password: in person, or over a channel you trust. Give it a short time with How long it works, and cancel it if it goes astray.

What the owner still approves

A code gives nothing by itself:

Nobody is in until someone lets them in. Using the code only asks to join. Someone who may invite, and who could have made the same offer, chooses Let sam in on their own device.
The rules still count. ZestSSH Cloud checks the team’s rules when the code is used, as for an invitation, and the review shows any that are not met. See Invitations and the rules.
Guests need an owner’s code. Someone whose address is outside the team’s proven domains can join only with a code an owner made, and only with an end date. See Guests.

What ZestSSH Cloud keeps while a used code waits: who used it, the platform their device’s session reports and when they used it, for the person who lets them in. The invitation goes when they are let in or turned away, or when the code runs out.

Next steps

Create a team and invite people: invitations by email, and comparing fingerprints.
Seats and billing: every waiting code holds a seat.
Guests: people from outside your company’s domains.
Vaults, access and roles: what the role and vaults on offer give.