Core concepts

workspace  (the account, the plan, the encryption key, the audit log)
   |
   +-- member         a person, holding one role for the whole workspace
   |
   +-- project        the boundary everything below is scoped to
         |
         +-- secret            a typed, versioned, encrypted value
         +-- secret group      a named set of secrets, injected together
         +-- SSH target        a server, reached by alias
         +-- database target   a database, optionally behind a bastion
         +-- AWS profile       a set of AWS credentials
         +-- k8s context       a cluster and its kubeconfig
         +-- profile           a named bundle of the four above
         +-- runbook           a versioned, reviewable procedure
         +-- access request    a time-boxed elevation, once approved

Two levels, and everything sensitive lives at the lower one. That is the whole structural idea: a person is a member of a workspace, but access is decided per project.

A workspace is the account. It owns the subscription, the encryption key that every secret inside it is ultimately wrapped by, the member list, and the audit log. It is called an organization in the API and the database.

• One person can belong to several workspaces and switch between them - their own, and any they have been invited into.

• Workspaces share nothing. No key material, no members' permissions, no audit entries cross between them.

• How many workspaces you may own depends on your plan. Workspaces you were invited into never count against that.

See Workspaces.

A project is the access boundary. Every secret, server, database, and grant belongs to exactly one, and permission is resolved per project - not per secret, and not per workspace.

The practical consequence: split by blast radius, not by tidiness. production and staging should be separate projects even for the same application, because the point of the boundary is that developer access to one does not imply access to the other.

Four roles, strictly ordered. Each one includes everything below it.

The full matrix is in Role capabilities.

A secret is a named, encrypted value in a project. Secrets are typed: a template says what shape the value has, which fields are sensitive, and where it is stored.

• Templates like env, plain, note, json_blob, and tls_certificate store into the generic secrets table.

• Templates like ssh_login, database_url, aws_keys, and kubeconfig store into their own resource tables instead - creating one of those *is* registering a piece of infrastructure.

• Non-sensitive fields (a hostname, a port, a region) are copied into metadata so they can be listed without decrypting anything.

Every write creates a new version rather than overwriting. On Pro and above you can read the history and roll back. A secret group names a set of secrets so they can be injected into a process together - that is what shortspan run <group> consumes.

A target is a piece of infrastructure registered with its credential: an SSH server, a database, an AWS profile, a Kubernetes context. Each has an alias, which is what you type.

An infrastructure profile bundles several targets under one name - "everything that makes up staging" - so a new engineer can enter an environment as a unit rather than being handed a list of aliases.

shortspan profile enter staging

Standing access to production is the thing worth avoiding. An access request asks for a specific project, for a stated reason, for a bounded number of hours. An admin approves or denies it, and approval creates a temporary grant that expires on its own.

Expiry is enforced by a scheduled job that runs every five minutes, and reminders go out before a grant lapses so nobody is cut off mid-incident without warning. Nothing has to be revoked by hand.

A runbook is a named, versioned sequence of steps - the operational procedure that otherwise lives in a wiki page nobody has read since it was written. Executing one is recorded, and a runbook can be marked as requiring approval before it will start.

An API token is a bearer credential with a set of abilities - secrets:read, ssh:use, runbooks:execute, and so on. Signing in with shortspan login mints one and stores it in your keyring; you can also mint one by hand for CI.

A device is the record of a CLI that completed the browser authorization flow: which machine, when, from where, and everything it has done since. Revoking a device kills its token immediately.

See API tokens and devices.