Shellius replaces static SSH keys with short-lived OpenSSH user certificates. Each organisation has its own Ed25519 certificate authority (CA). Hosts trust the CA's public key, so there is nothing to copy to a host when a person joins, and nothing to clean up when they leave.

You rarely handle certificates directly — approving an access request is what causes one to be issued. This page explains what is issued, how to inspect and revoke it, and how the CA itself is managed.

Required permissions

Permission	Label in Roles	What it allows
—	—	Everyone can always see their own certificates.
certificates.view_all	View all certificates	See every issued certificate in the organisation.
certificates.revoke	Revoke certificates	Revoke any issued certificate.
certificates.issue_direct	Issue certificates directly	Sign a certificate through the API, outside the request flow.
ca.view	View CA	See the CA public key, fingerprint and status.
ca.rotate	Rotate CA	Replace the organisation's CA key pair. Super admin only by default.

When a certificate is issued

A certificate is signed at the moment it is needed, never in advance:

• when you open a browser terminal to a certificate-mode server, or
• when you download SSH credentials from an approved request, which the shellius terminal client also does on your behalf.

Each time, Shellius generates a fresh Ed25519 key pair, signs the public half with the organisation CA, hands the result over once, and deletes its copy. The private key is never written to the database.

Servers that connect with a stored Keystore identity do not use certificates at all.

What a certificate contains

Field	Value
Type	OpenSSH user certificate, Ed25519
Key ID	ar- followed by the access request ID, so sshd logs on the host tie a login back to a request
Serial	A unique number. This is what the host sends back to Shellius to validate the connection.
Principals	The login user granted by the request
Valid after / Valid before	From the moment of signing until the access request expires

The lifetime is whatever time is left on the access request when the certificate is signed. A request approved for two hours, used 90 minutes in, yields a certificate that lives 30 minutes. Shellius refuses to sign when fewer than 60 seconds remain.

Shellius also records who the certificate was issued to, which server it was issued for, and how it was issued. The server binding matters: see below.

How a host validates a certificate

A valid CA signature is not enough to log in. On every connection, sshd on the host runs check-principals, which calls the Shellius API with the host's own agent token. Shellius answers "valid" only if all of these hold:

• the serial exists, and the certificate is not revoked or expired,
• the current time is inside its validity window,
• the login user being attempted is one of its principals,
• it was issued for this host — a certificate for one server is refused on every other server, even one with the same login user,
• the access request it was issued under is still approved and unexpired.

That last check is why revoking an access request takes effect on the next connection attempt, without touching the host and without waiting for the certificate to run out.

View certificates

Open Certificates. With certificates.view_all you see the whole organisation's; otherwise you see your own. The list shows Serial, Issued to, Server, Principals, Status and Valid until, and can be filtered by status.

Status	Meaning
ACTIVE	Inside its validity window and not revoked.
EXPIRED	Past Valid before. A background job marks these every five minutes; the host refuses them on time regardless.
REVOKED	Ended early. Revoked at and Revoked by are recorded.

View details shows the full record. Download .pub saves the signed certificate — the public half only. The private key cannot be retrieved after issuance, because Shellius does not have it.

Revoke a certificate

1. Open Certificates and find the certificate.
2. Choose Revoke and confirm.

The host refuses the certificate from the next connection attempt. Revoking an access request does this for you and also prevents a new certificate being signed under the same request, so prefer that when you want to end someone's access rather than one credential.

What happens to sessions that are already open

Revoking a certificate only stops new connections. Revoking the access request goes further: browser SSH sessions opened under it are ended automatically, within about 30 seconds. A shell opened with your own ssh client does not pass through Shellius, so Shellius cannot close it — it lasts until the user exits or the host drops it. RDP sessions are ended from Sessions.

Using a downloaded certificate

When a policy allows key download, an approved request offers a private key, a certificate and a ready-made command:

ssh -i id_ed25519 -o CertificateFile=id_ed25519-cert.pub \
  -o StrictHostKeyChecking=accept-new [email protected] -p 22

Save both files with the names in the command and restrict the key with chmod 600 id_ed25519. This connection leaves from your machine, so your machine needs a route to the host — see Network reachability.

Issue a certificate through the API

POST /api/certificates/issue signs a public key you supply, for automation that cannot use the request flow. It needs certificates.issue_direct and is deliberately narrow:

• every principal is still checked against policy for the target server,
• production is refused — production certificates are only issued for an approved access request,
• validity is between 60 seconds and 7 days,
• only user certificates, only the standard extensions (permit-pty, permit-port-forwarding, permit-agent-forwarding, permit-X11-forwarding, permit-user-rc), and no critical options,
• issuing for another user additionally needs users.update and the right to manage that user.

The certificate authority

Open Administration → Certificate authority to see the active CA's fingerprint, public key, creation and last-rotation dates, and how many certificates it has issued. The public key is what the bootstrap script installs on each host as /etc/ssh/shellius_ca.pub and points sshd at with TrustedUserCAKeys. You only need to copy it by hand if you are trusting Shellius on a host without using the bootstrap script.

The CA private key is encrypted at rest and decrypted in memory only for the duration of a signing operation. It is never shown in the portal or returned by the API.

Rotate the CA

Rotation generates a new Ed25519 key pair, makes it the active CA and retires the old one. It is audited as ca.key_pair.rotated.

Rotation is disruptive and cannot be undone

Hosts keep trusting the old public key until they are given the new one. After rotation, newly issued certificates are refused by every host that has not been updated, and nothing pushes the new key out for you. The agent's --upgrade mode does not touch CA trust.

1. Plan a window. Until a host has the new CA public key, certificate logins to it fail.
2. Open Administration → Certificate authority and choose Rotate certificate authority. Confirm.
3. On every managed host, install the new public key — re-run the bootstrap command for that server, or replace /etc/ssh/shellius_ca.pub with the key shown in the portal.
4. Ask people to request access again so that fresh certificates are signed by the new CA.

Rotate when you believe the CA private key or the server encryption key has been exposed, and keep a way into your hosts that does not depend on Shellius while you do it.

Next steps

Access requests and approvalsThe workflow that leads to a certificate being signed.How Shellius worksThe whole flow, from bootstrap to a refused connection.Threat modelWhat the CA protects against, and what it does not.Hardening checklistProtect the keys that protect the CA.