Access model

GrantSSH does not proxy SSH connections or validate passwords at login time. Access is enforced by key presence: while a permission is active, the open-source agent places the member's public key in the server account's authorized_keys file. When the permission is inactive, the key is removed. This page explains how permissions, schedules, keys, and agent sync combine to produce that result.

For the objects involved — teams, servers, accounts, and grants — see Core concepts. For step-by-step grant management, see Managing permissions.

The enforcement chain

SSH access through GrantSSH depends on four layers working together:

1. Permission — a grant linking a team member or group to a server account, optionally with a schedule.
2. Active schedule — at the moment the agent polls, the permission must pass all schedule rules (dates, weekdays, time window). If any rule fails, the permission is treated as inactive.
3. SSH public key — the granted member must have at least one public key uploaded and assigned to them. Without a key, an active permission produces nothing on the host.
4. Agent sync — on each poll, the agent on an active server fetches the current set of active permissions and keys, then updates authorized_keys for each managed server account.

A user connects with a normal SSH client using their private key. If their public key is present in authorized_keys, the connection succeeds. If it is absent, SSH authentication fails — GrantSSH is not in the connection path.

Permissions vs team roles

Team roles (Owner, Manager, Member) control who can manage servers, grant access, and approve requests. They do not, by themselves, grant SSH access to a host.

Permissions (shown in the app as team access or active grants) control who can connect to which server accounts and when. A manager without a permission for deploy@production cannot SSH there any more than a member can — unless someone grants them access like any other team member.

What makes a permission active

The dashboard Active grants count and the agent sync API both evaluate permissions at a point in time — UTC for sync. A permission is active when every schedule dimension that is set passes simultaneously. Dimensions that are left empty impose no restriction on that axis.

In practice:

• No schedule configured — the permission is always active until you change or end it.
• Start date — inactive before this calendar date (inclusive from start date onward).
• End date — inactive after this calendar date (inclusive through end date).
• Days of week — inactive on weekdays not selected in the grant.
• Time window — inactive outside the start–end time on days when the permission otherwise applies.

Permissions that have passed their end date may still appear in Team access with an Expired badge for audit purposes. They no longer sync keys to the host.

Schedule rules

When creating or editing a permission, you choose one of three schedule types. They are mutually exclusive in the grant form — you cannot combine a date range with weekday rules in a single permission.

Time windows apply to the same calendar day only — a window from 22:00 to 06:00 UTC does not span midnight as a single continuous overnight block. Use separate grants or date ranges if you need that pattern.

Key presence

GrantSSH stores public keys only. Each team member uploads keys on the SSH keys page; keys are assigned to the member who added them.

For a given server account at sync time, the agent includes a public key when:

• There is an active permission for that account, and
• The key is assigned to the same subject as the permission (the user or group named in the grant).

If a member has multiple public keys, all keys assigned to them are eligible for sync while any of their permissions for that account are active. Removing a key from the dashboard removes it from future syncs even if a permission remains active.

See Working with SSH keys for upload, fingerprinting, and assignment details.

Agent sync

The agent on each host periodically calls the GrantSSH API to fetch the desired state for that server. Sync only returns account and key data when the server status is Active — pending servers receive status only, with no keys to apply.

On each sync, for every server account the team has defined:

1. Collect permissions that are active at poll time (UTC).
2. For each active permission, find public keys assigned to the grant's subject.
3. Rebuild authorized_keys for that Linux user from the resulting key set.

The agent does not merge keys from inactive permissions. If no permissions are active for an account, the managed keys GrantSSH placed there are removed on the next successful sync.

Poll interval is configured on the agent host, not in the dashboard. Changes typically appear within 30–120 seconds after a grant, schedule edit, or access removal — allow one sync cycle before testing SSH.

Group permissions

A permission can target a group instead of an individual member. Every member of the group is considered to have access for dashboard purposes — they see the server under My accounts and can open Connect when the grant is active.

On the host, sync still keys off the group subject on the grant. Each member needs their own public keys uploaded; keys are assigned to users, not to groups directly. Adding or removing someone from a group changes who receives access through that grant on the next evaluation, without creating separate permissions per person.

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

When access ends

Access becomes inactive when any of the following is true at sync time:

• The schedule window closes (end date passes, weekday does not match, or time is outside the allowed range).
• An owner or manager edits the permission to a narrower schedule or an end date in the past.
• The server account or group linked to the permission is deleted in GrantSSH.
• The server is no longer Active (sync stops delivering keys entirely).
• The member's public keys are removed from the team.

Inactive permissions remain in the database for audit unless the underlying record is deleted. The agent omits them from sync payloads, which removes the associated keys from authorized_keys on the next poll.

Limits and expectations

• Near-real-time, not instant — revocation and expiry take effect on the agent's next poll, typically within 30–120 seconds.
• UTC evaluation — all schedule boundaries use UTC at poll time.
• One grant per subject and account — you cannot stack duplicate permissions for the same member-or-group and server-account pair; edit the existing grant instead.
• Active server required — keys never sync to pending hosts.
• Stale agents — if an active server stops checking in, the dashboard may mark it Stale. That reflects connectivity health; it does not by itself change permissions in the app.

What GrantSSH does not enforce

GrantSSH intentionally focuses on managed authorized_keys sync and auth-event reporting. It does not:

• Act as a bastion host, SSH proxy, or VPN.
• Record or replay interactive shell sessions.
• Filter commands or restrict what a user runs after they connect.
• Store or validate SSH passwords — authentication is key-based only for managed access.
• Guarantee sub-second revocation — enforcement follows the agent poll interval.

Activity and auth logs report what the agent observes on the host (logins, disconnects, sudo usage, failed login summaries). See Auditing activity.

What to read next

• Managing permissions — grant, schedule, and end access in the dashboard.
• Working with SSH keys — upload, assignment, and sync behaviour.
• Agent configuration — sync endpoint, credentials, and service setup.
• How it works — product-level overview of the access lifecycle.
• Security — keys, data handling, and responsible disclosure.