Create a team and invite people

Adding someone to a team takes two steps. First you invite them and they accept. Then their keys are checked, and only then do you add them. Nothing is shared with them before that second step.

There are two ways to invite:

By email. You invite their address, they accept, and you compare fingerprints with them on a call or in person before you add them. This page explains it.
With a code or QR code. You make a one-time code on your device and give it to them. The code checks both sides’ keys, so there is nothing to compare by hand, and you still let them in. See Join a team with a code.

Before you start

Sign in to your ZestSSH account on the device. You do not need sync first: your team keys are made on the device when you make the team. See What a team needs.
Seats. You hold a seat in your own team, and every invitation takes one while it stands. A new team has no seats until an owner buys some or redeems a seat code; with the personal Bundle, your own seat is included. Without enough seats the team takes no new items and no new invitations. See Seats and Business.
The people you invite need a ZestSSH account that uses the address you invite. See Your team keys.

Create a team

Open the space switcher. On a computer it is in the bar at the top of the window. On a phone, tap the name at the top of the Hosts tab.
Choose Create a team.
Read the note under the title: “Each person in a team holds a seat, bought once. With the Bundle, your own seat is included.”
Under Team name, type the team’s name, for example “Example Ops” (up to 50 characters).
Choose Create team.

ZestSSH makes the team, switches to it and says “Example Ops is ready”.

If sync is off on the device, ZestSSH then shows Turn on sync for your team, so your team keys can reach your other devices:

The team has a seat bought: “Your team includes ZestSSH Cloud sync for everyone in it.” Set up sync opens your account page.
No seat yet: an owner sees Buy seats; once the team has a seat, sync is included. Until then your team keys stay on this device only.

Later, when a team’s seat first gives you sync and it is still off on a device, a notice there says so, with Set up sync. The team’s Seats page says it too.

What a new team has

You, as its only owner. Make a second owner once you trust someone: see Hand over or share ownership.
One vault, Shared. It allows SFTP and port forwarding, not agent forwarding.
One role, Member. It gives Use in Shared and no powers in the team. Until the owners make other roles, it is the role an invitation offers unless you pick Admin.
No rules, and nothing recorded about how members use it.

The team’s key and the vault’s key are made on your device. ZestSSH Cloud receives them only sealed to your account key.

An account can own up to 20 teams. Past that, ZestSSH says “This account owns as many teams as it can for now.”

Invite someone

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

Open the Team pages. On a computer, choose Invite people on Overview or Members. On a phone, use the invite button on Overview (Invite people), or open Members and choose Invite someone under Invitations.
The dialog Invite to Example Ops says “Choose how they get the invite, then what they can open.” Choose Email (“For one address, checked by fingerprint”). For a code instead, choose Code or QR and see Join a team with a code.
Under Email addresses, type the address of the account they sign in with, for example robin@example.com. To invite several people with the same offer, type or paste more: a comma, a semicolon or a space between addresses turns each into a chip, and the cross on a chip removes it.
Under What they get, pick the Role. You see the roles below your own. Owners also see Admin: “Admins open every vault except owners-only ones, invite people, add vaults, and manage everyone below Admin.”
Optional: under Vaults, pick a level for a vault. Each vault says what the role gives there, for example “Use, from Member” or “Member gives None”. A level above the role’s is marked Extra. You can offer only the levels you hold in that vault yourself, and owners-only vaults are not listed. An admin gets no extra vaults.
Optional: next to Access ends, choose Pick a date, pick a day and choose Save. “Their access lasts through the day you pick.” Never takes the end date away.
Choose Send invitation, or Send invitations for several addresses.

Before you send, the dialog says what the invitations take, for example “Seats this takes: 2 of 3 open”, or “Takes your last open seat”. If there are not enough seats, it says so before anything is sent, for example “Every seat is taken. You need 1 more seat to invite someone.” On a computer, an owner sees Buy 1 seat, which opens zestssh.com ready to buy exactly those. On a phone or tablet an owner sees “Seats and Business are managed from ZestSSH on a computer.”, and anyone else “Only owners buy seats. Ask an owner if this team needs more.”

For one address, ZestSSH says “Invitation sent to robin@example.com”. If no email went out, it says “Invitation saved. robin@example.com sees it in ZestSSH after signing in with that address.” For several, it says “Invitations sent”. An address that could not be invited stays in the dialog with the reason (“Not sent to robin@example.com:” and why), so you can try again. An invitation that was made stands either way, and someone already signed in to ZestSSH with that address hears of it at once.

The invitation shows under Invited with the role and Waiting for them to accept.

An invitation never offers Owner: add the person first, then use Make owner.

Accept an invitation

If someone invited you:

Sign in to ZestSSH with the address you were invited at.
Open the space switcher and choose Invitations. A dot on the switcher shows that one is waiting. While your account is in no team yet, ZestSSH looks for new invitations every two minutes and when the app comes back to the front, and puts a notice in the bell: “You’re invited to join a team”.
Read it: who invited you (“alex@example.com invited you to a team”), the role, how many vaults it opens and the day the invitation lapses. If your access would end, it says “Your access would end on” and the date. It also says what the team records about how members use it, whether the team sends its events to a system of its own, and how many of the vaults you would open log or watch sessions.
Choose Accept, or Decline. Accepting needs your team keys on this device: see Your team keys.
After Accept, the dialog says “Accepted. Next, they compare fingerprints with you and add you. Read them yours when they ask:” and shows your eight words. Keep them at hand for the call.

You are not in the team yet, and nothing of it is on your device. Your app keeps a line open to ZestSSH Cloud, so the team arrives the moment you are added.

What an invitation does not show:

The team’s name. It is encrypted for members.
The name of a role the owners made. Role names are encrypted too, so such a role shows as Member until you are in.

If the team’s rules ask for something you do not have yet, such as two-step sign-in, the invitation says “This team asks for two-step sign-in first. Fix that, then accept.”

Your team keys

Everything a team hands you is sealed to your team keys, so they must be on the device you accept on. When you choose Accept, or join with a code, ZestSSH checks first:

The keys are not made yet: ZestSSH makes them and goes on, sync on or not. Once you are in a team with a seat bought, it includes ZestSSH Cloud sync: turn it on so the keys reach your other devices. See Cloud sync.
Another of your devices made them: Your team keys are on another device: “They come to this device once it syncs with the same storage and sync password as that one. Sync now, then accept.” If they have not come yet: “They aren’t here yet. Let sync run on your other device, then sync here again.” If you no longer have that device, choose I don’t have that device: “No longer have it? Start over with new keys on your Account page, under Your keys.”

Compare fingerprints and add them

When the person accepts, their invitation moves to Waiting for you and shows Accepted: compare fingerprints to add them, and the Overview lists it under Needs attention: “1 person accepted and waits for you”.

Call the person, or meet them. Do not do this by email or in a chat.
Under Waiting for you, choose Compare and add next to them. On a computer’s Members page, click their card instead: the review opens beside the list, and Let robin in starts the comparison.
The dialog Add robin@example.com? shows the words they should read to you. Ask them to read out the words shown under Invitations in their ZestSSH. Use digits shows the same fingerprint as 60 digits instead.
If every word matches, choose It matches, add them. If any word differs, choose Cancel and find out why before you try again.
If Confirm it’s you appears, choose Sign in again and sign in, with your second step if you use one. Adding someone needs a sign-in from the last 10 minutes.

ZestSSH says “robin@example.com is a member now.” They get the keys of the team and of the vaults offered, sealed to the keys you just compared, and your device marks them as verified. The other members see that you checked them.

Anyone who may invite can add people, as long as they could have made the same offer: an invitation into Admin can be confirmed only by an owner. Your device must also hold the keys being handed on: if it cannot open a vault the invitation offers, ZestSSH says “A vault offered can’t be opened on this device, so it can’t be handed on from here. Ask the owner to add them.”

Why you compare fingerprints

A fingerprint is a hash of a person’s two public account keys, the one that signs and the one that keys are sealed to. ZestSSH shows it as eight numbered words from the BIP-39 English word list (88 bits), or as 60 digits. Every device of the same account shows the same words.

When someone joins, their public keys reach you through ZestSSH Cloud. A server that knows every public key could show you a key of its own, and the team’s keys would then be sealed to it. ZestSSH cannot tell that from the keys alone. Comparing the words over a separate channel, a call or a meeting, proves that the keys are really the person’s. This is the only check against a key swapped at the moment someone joins, so do not skip it.

After you add someone, your device pins their keys:

If they later replace their keys and their old keys vouch for the new ones, your device follows, and shows Keys replaced since you compared until someone compares again.
If new keys arrive that their old keys did not vouch for, your device stops: “Until someone compares the new fingerprint with them, ZestSSH ignores what the new keys sign and seals nothing to them.” They show as Keys changed.

Only members you have verified can be made an Owner or Admin. The team’s record carries your signed statement that you compared them, and every member’s app checks it.

Before someone is added

While an invitation waits:

Nothing is shared. No keys, no vault names, not even the team’s name.
It lapses after 14 days. Inviting the same address again updates the role, vaults and end date and gives 14 more days. No second email goes out while the first invitation has not lapsed. Someone who already accepted stays accepted.
You can send it again. Resend next to an invitation that waits sends the email again and gives it 14 more days: “Sent to robin@example.com again”.
You can send a code instead. Send a code instead makes a one-time code with the same offer, for when the email does not arrive. The email invitation goes once the code is used. See Send a code instead of an email invitation.
It holds a seat.
You can withdraw it. Choose Withdraw invitation (in the row’s menu on a computer, the cross on its row elsewhere). Whoever made the invitation can withdraw it, and so can anyone who could have made the same offer.
The rules count. ZestSSH Cloud checks how they signed in when they accepted against the team’s rules as they stand now. If that falls short, for example because an owner turned on two-step sign-in after they accepted, the row says “Accepted without two-step sign-in. They fix that and accept again before you can add them.”
Their keys must stay the same. If they replaced their keys after accepting, adding them stops with “Their keys changed since this list was read. Compare the new fingerprint with them.”
The end date must not have passed. An invitation whose access end date has already passed cannot be confirmed.

After they join: check each other

The new member’s device pins everyone’s keys the first time it sees them, without a check. So the new member should compare fingerprints with the person who added them, and with anyone else they work with.

In Members, each person shows where your device stands with their keys:

Status	What it means
Verified by you	You compared their words.
Verified by 2 members	Others compared them, and your device checked their signed statements.
Not verified	Nobody your device trusts has compared them yet.
Keys replaced since you compared	Their old keys vouched for new ones. “Compare again to be sure it was them.”
Keys changed	New keys their old keys did not vouch for. Nothing new is sealed to them.
No keys yet	There is nothing to compare.

To compare with a member:

Open Members and open the person. On a computer, click their row and choose Compare codes in the panel. Elsewhere, choose Compare fingerprints in the row’s menu.
The dialog Compare codes with robin@example.com shows two lists: Your words (“You read these out”) and robin@example.com’s words (“robin@example.com reads these out”). They see the same two lists, swapped, so one call checks both of you.
If every word matches, choose They match. ZestSSH says “robin@example.com’s keys are verified.”

On a phone, Scan their code checks their screen with the camera; any device can Show my code. Each of you marks the other verified on your own device.

Your own words are in Members: under Your fingerprint, or on a computer in your own row’s panel under Your words. They are also on the Account page under Your keys.

Common problems

Message	What to do
”Sign in to use teams.”	Sign in to your ZestSSH account.
”Your team keys aren’t on this device yet. Set up sync on this device and let it sync once, then try again.”	Set up sync on the device, let it sync once, and try again.
”Every seat in this team is taken. An owner can buy more on the Team page, under Seats.”	An owner buys seats, or you withdraw an invitation that is not needed.
”That’s a lot of invitations for one hour. Try again later.”	An account can send 30 invitations an hour.
”They’re already a member.”	They are in the team already.
”Your role can’t make that invitation. You can invite people only into roles below your own, and give no more access than you have.”	Pick a lower role, or fewer vaults.
”They do not meet this team’s rules yet: …”	The address is outside the team’s Allowed email domains, or they accepted without a rule the server checks.
”The invitation lapsed. Invite them again.”	Invite the address again.

Limits

Matched by address. An invitation goes to the account that signs in with exactly that email address. If someone’s account uses a private relay address, for example from Sign in with Apple, invite that address.
One invitation per address. Inviting an address again replaces the earlier offer for it.
No owners by invitation. Invite someone, add them, then make them an owner.
Comparing is a human step. If nobody compares, a swapped key can go unnoticed. The Overview reminds owners and admins of members nobody has verified yet. An invite code does this check for you: see What the code proves.

Next steps

Join a team with a code: invite with a one-time code or QR code.
Vaults, access and roles: decide what each role opens.
Guests: inviting people from outside your company’s domains.
Suspend, remove and leave: when someone should no longer be in.
Teams overview: roles, encryption and seats.