Working with SSH keys - Documentation

GrantSSH manages SSH access by placing team members' public keys in each server account's authorized_keys while a permission is active. You create and keep private keys on your own machine; GrantSSH never sees them. This guide covers creating keys, uploading them, and what happens on the server side.

For the product vocabulary around keys, permissions, and the agent, see Core concepts. For a first-time setup walkthrough, start with the quick start guide.

Public keys only

SSH authentication uses a key pair: a private key that stays on your computer and a public key that you can share. GrantSSH stores public keys only. A public key on its own cannot be used to log in — someone would also need the matching private key.

GrantSSH does not:

Generate private keys for you in the app
Accept pasted private keys
Store SSH passwords or host credentials

When you paste a key into the dashboard, paste the public key — typically a single line starting with ssh-ed25519 or ssh-rsa, or the contents of a *.pub file. Never paste the private key file (often named id_ed25519 or id_rsa without the .pub suffix).

Create a key pair

GrantSSH is bring-your-own-key. Create a key pair on a machine you control before adding the public half to your team.

Recommended approach on macOS, Linux, or WSL:

ssh-keygen -t ed25519 -C &quot;[email protected]&quot;

ssh-keygen prompts for a file location (default ~/.ssh/id_ed25519) and an optional passphrase. Use a strong passphrase so a stolen private key file is not immediately usable.

Your public key is written alongside the private key, usually as ~/.ssh/id_ed25519.pub. To display it:

cat ~/.ssh/id_ed25519.pub

Helpful tools on this site:

ssh-keygen command generator — build a correct command for your OS and options
SSH key generator — create an ed25519 pair in the browser when you cannot run ssh-keygen locally (add a passphrase with ssh-keygen -p after download)

Add a key in GrantSSH

Any team member can add keys for themselves:

Open SSH keys in the main navigation.
Choose Add SSH key.
Optionally enter a name (for example MacBook Pro or CI runner).
Paste your public key into the text field.
Choose Add key.

The key is assigned to you automatically. Managers and owners cannot add keys on behalf of other members — each person uploads their own public keys.

If you paste multiple lines, GrantSSH uses the first non-empty line. Trailing comments on the key line (the optional email at the end) are preserved.

How keys are stored

SSH keys in GrantSSH are team-scoped. The same public key fingerprint can exist once per team. When you add a key, GrantSSH stores the public key material and links it to your user account via an assignment.

If you remove a key from your account and add the same public key again later, GrantSSH reuses the existing team record and creates a new assignment — you do not duplicate key data.

Keys are not tied to a single server. One public key on your account can be placed on every server account you have been granted access to, for as long as those permissions are active.

How keys reach servers

GrantSSH does not push keys the moment you click save. The open-source agent on each managed server polls GrantSSH for the current access state and updates authorized_keys locally.

An owner or manager grants you access to one or more server accounts (see Managing permissions).
While that permission is active, your assigned public keys are included in the sync payload for those accounts.
The agent writes the allowed keys into each account's ~/.ssh/authorized_keys (or the path configured for that account).
When the permission ends or is revoked, your keys are removed on the next sync cycle.

Changes typically apply within one sync cycle — roughly 30–120 seconds. The server must be active (approved in the dashboard) or the agent will not receive keys to apply.

Fingerprints and identification

Each stored key has a SHA256 fingerprint shown in the SSH keys list. Fingerprints identify keys without exposing the full public key material — useful when comparing a key in GrantSSH to one on a server or in your local ssh-keygen -l output.

On your machine, fingerprint the public key file with:

ssh-keygen -l -f ~/.ssh/id_ed25519.pub

When the agent reports a login, GrantSSH can attribute the event to the team member whose stored public key matches — giving you an audit trail tied to people, not just IP addresses.

Multiple keys per person

You can assign several public keys to the same account — for example a laptop key and a separate CI key. When any of your permissions are active, all of your assigned keys are eligible for sync to the granted server accounts.

Use descriptive names so you can tell keys apart in the dashboard and when reviewing activity. There is no hard limit on keys per member beyond what your team plan allows for team size and usage.

Remove a key

From SSH keys, choose Delete on the key you want to remove. This removes the key's assignment from your account. It does not delete the underlying team key record if another member still uses the same public key (uncommon).

After removal, the agent drops that key from authorized_keys on the next sync for every server account where it was present. You can add the same public key again later if needed.

Connect with the right key

GrantSSH does not change how you use SSH. Connect with your normal client, using the private key that matches the public key you uploaded.

From the dashboard, open Servers → My accounts and use Connect to copy a suggested ssh user@host command. If you have multiple private keys, tell SSH which one to use:

ssh -i ~/.ssh/id_ed25519 [email protected]

Or add a Host block to ~/.ssh/config. The SSH config generator can help you build one.

Troubleshooting

Permission denied (publickey) — confirm the public key in GrantSSH matches the private key you are using (ssh -i or IdentityFile in config). Wait for an agent sync after granting access. Ensure the server is active and the permission is currently in effect.
Invalid SSH public key format — paste a single-line OpenSSH public key (ssh-ed25519 AAAA... or ssh-rsa AAAA...), not a private key or PEM block.
Key added but not on the host — check that you have an active grant for that server account, the server is approved, and at least one sync cycle has passed. Pending servers do not receive keys.
Wrong key after rotation — add the new public key in GrantSSH, confirm access with the new private key, then remove the old public key so the agent stops syncing it.
Auditing shows the wrong person — attribution depends on matching the login to a stored public key. Shared keys or manual edits to authorized_keys outside GrantSSH can break attribution. Prefer one key per person where possible.