Core concepts

GrantSSH manages SSH access by keeping each server's authorized_keys in sync with the permissions you define in the dashboard. This page explains the building blocks — teams, servers, accounts, keys, and grants — and how they relate. For a hands-on walkthrough, start with the quick start guide.

Teams and roles

A team is your workspace. Servers, SSH keys, permissions, groups, and billing all belong to a team. When you sign up, you create a team and become its owner. Additional people join as invited members with a role on that team.

GrantSSH has three team roles:

• Owner — full control of the team, including billing, team settings, and ownership transfer. Owners can do everything managers can.
• Manager — can add and approve servers, manage server accounts, grant access, review access requests, and invite members. Cannot delete the team or transfer ownership.
• Member — can add their own SSH keys, browse team servers, request access, and connect to accounts they have been granted. Cannot add servers or grant permissions to others.

Owners and managers land on the Dashboard after login. Members land on Servers, focused on the hosts they can reach.

Servers

A server is a Linux host your team manages through GrantSSH. Each server has a name in the dashboard and runs the open-source GrantSSH agent, which checks in with the app and applies permission changes on the host.

Every server moves through a simple lifecycle:

• Pending — the server record exists but is not yet trusted for access sync. New servers start here. The dashboard may show Awaiting claim until the agent connects.
• Active — an owner or manager has chosen Approve server. Only active servers receive permissions and SSH keys from the agent.

Active servers that stop checking in may appear as Stale in the servers list. Until a pending server is approved, the agent will not sync keys — even if it is installed and running.

The agent

The GrantSSH agent is a small open-source program installed on each managed server. It authenticates to GrantSSH with credentials issued during setup, sends periodic heartbeats with host metadata, pulls the current list of server accounts, permissions, and SSH keys, and updates authorized_keys accordingly. It also reports SSH activity back to the app for auditing.

The agent does not proxy SSH connections and does not hold anyone's private keys. It only adds or removes public keys on the server while a permission is active. Changes typically apply within one sync cycle (roughly 30–120 seconds).

Install the agent with the script served from the GrantSSH app. See Quick start for the claim-code flow or Installing the agent for enrolment tokens and advanced setup.

Claim code vs enrolment token

There are two ways to connect an agent to your team. Both result in a pending server that must be approved.

Server accounts

A server account is a Linux user on a managed host — for example deploy or ubuntu. GrantSSH does not auto-discover users on the server; owners and managers add accounts explicitly under the server's Accounts (also labelled Server users in the app navigation).

Permissions attach to server accounts, not to servers as a whole. Deleting an account in GrantSSH removes associated permissions in the app but does not delete the Linux user on the host.

SSH keys

GrantSSH stores public SSH keys only. Each team member adds keys on the SSH keys page; keys are team-scoped and assigned to the person who added them. Private keys never leave the user's machine.

When a permission is active, the agent places the granted member's public key in the authorized_keys file for each allowed server account. When the permission ends or is revoked, the key is removed on the next sync. Users connect with normal SSH clients — no custom jump hosts or proxies.

Permissions and team access

A permission (shown in the app as team access or an active grant) links a team member or group to one or more server accounts, optionally with a schedule — start and end dates, days of the week, or a daily time window.

Owners and managers create permissions with Grant access on a server's Team access page. While a permission is in effect, the member's key is present on the host; when it is not, the key is absent. Existing SSH sessions are not terminated when access ends, but new connections cannot be opened without a valid grant.

How schedules, key presence, and revocation interact is covered in Access model.

Groups

A group is a named set of team members. Instead of granting access to individuals one at a time, owners and managers can grant a permission to a group so every member receives the same server accounts and schedule. Groups are managed from a server's Groups section under team access.

Deleting a group removes permissions that were assigned to that group.

Access requests

Members cannot grant themselves access. They submit an Access request for a server, select the server accounts they need, provide a reason, and optionally propose a schedule. Owners and managers review pending requests and approve or deny them; approval creates the same kind of permission as Grant access.

Managers and owners do not use the access-request flow for themselves — they grant access directly. Only one pending request per server per member is allowed at a time.

Activity and auth logs

The agent reports authentication events from the host. Activity in the main navigation shows team-wide events: Login, Disconnect, Sudo, and Failed logins. Each server also has Auth logs with the same event types filtered to that host.

When the agent can match a login to a stored public key, the event is attributed to the corresponding team member. This gives you an audit trail of who connected, when, and from where — without GrantSSH ever SSHing into your servers. See Auditing activity for event types, filtering, and review workflows.

What to read next

• Quick start — set up your first server end to end.
• Auditing activity — logins, disconnects, sudo usage, and failed login summaries.
• Access model — how permissions, schedules, and key sync enforce access.
• Roles and permissions — detailed capability matrix for owners, managers, and members.
• How it works — product-level overview of the access lifecycle.
• Security — keys, data handling, and responsible disclosure.