Documentation
Everything Shortspan does, written down.
Shortspan brokers short-lived credentials for secrets, servers, databases, and cloud accounts, and records every time one is handed out. These pages cover the command line, the console, the REST API, the security model, and running the whole thing yourself.
Start with the concepts
What Shortspan is, the seven nouns it is built from, and how a credential actually reaches your shell.
IntroductionGet something working
Create a workspace, store a secret, and run a command against it - about ten minutes end to end.
QuickstartLook something up
Every CLI command and flag, every API endpoint, every error code, and the full plan matrix.
Command referenceGetting started
What Shortspan is, and how to get a credential out of it in ten minutes.
- IntroductionShortspan brokers short-lived credentials for secrets, servers, databases, and cloud accounts so nothing sensitive has to live on a developer machine.
- How it worksThe path a credential takes from the encrypted store to a process on your laptop, and everything that is recorded along the way.
- QuickstartCreate a workspace, store your first secret, and run a command against it - start to finish in about ten minutes.
- Core conceptsWorkspaces, projects, secrets, targets, profiles, runbooks, and grants - the seven nouns the rest of the documentation assumes.
Command line
The primary interface. Everything below runs on your machine and holds nothing on disk.
- Installing the CLIInstall the shortspan binary on macOS, Linux, or Windows, and verify that it is talking to the right host.
- Signing inThe browser device flow, where the token is stored, and how to authenticate on a machine that has no keyring.
- ConfigurationThe config file, the active organization and project, and the environment variables that override both.
- Working with secretsCreate, list, read, and inject secrets - including the commands that never print a value to your terminal.
- SSH accessOpen a session on a registered server without ever holding its key, and run one command across a fleet.
- Database accessConnect a database client through a brokered credential, tunnel through a bastion, or run the client on the server itself.
- AWS and KubernetesInject AWS credentials into a subshell and switch kubectl contexts without writing either to disk.
- Infrastructure profilesBundle the servers, databases, and cloud accounts that belong to one environment, and enter them as a unit.
- RunbooksRun reviewed, versioned operational procedures, including the ones that require an approval before they start.
- Deploying with a runbookSet up a server so a runbook can deploy to it as an unprivileged account - the account, the sudo rule, the deploy key, and a check that proves it all works before the first run.
- Command referenceEvery command, argument, and flag the CLI accepts, with its exit behaviour.
Web console
Where access is granted, reviewed, and revoked.
- First-run setupThe four steps between signing up and having a workspace someone can actually work in.
- WorkspacesBelonging to more than one workspace, switching between them, and what an invitation actually grants.
- ProjectsThe boundary every secret, server, and grant is scoped to, and the reason to have more than one.
- Secrets and groupsTyped secret templates, version history, rollback, and the named groups that back shortspan run.
- InfrastructureRegistering SSH servers, databases, AWS profiles, and Kubernetes contexts, and the per-server security policy.
- Access requestsAsking for temporary access, approving it, and what happens when the clock runs out.
- Runbooks and approvalsAuthoring a runbook, versioning it, requiring approval, and reading the execution record afterwards.
- Team and invitationsInviting people, assigning roles, resending and revoking offers, and removing someone cleanly.
- Audit logWhat is recorded, what is deliberately not, and how to answer "who read that secret".
Account and billing
Your own credentials, and what the workspace is paying for.
- Account securityPasswords, two-factor authentication, passkeys, recovery codes, and the emails that tell you something changed.
- API tokens and devicesMinting scoped tokens for automation, reviewing authorized CLI devices, and revoking either in a hurry.
- Plans and billingWhat each tier includes, how limits are enforced, and how to change or cancel a subscription.
REST API
The same surface the CLI uses, documented for your own tooling.
- API overviewBase URL, versioning, response envelopes, rate limits, and the transport rules the API enforces.
- AuthenticationBearer tokens, token abilities, the device authorization flow, and how the API answers a suspended account.
- Endpoint referenceEvery v1 endpoint, the permission it requires, and the shape it returns.
- Pipeline APIThe machine-to-machine endpoint a build pipeline uses to publish a CLI release.
Security
The claims Shortspan makes, and the mechanisms behind them.
- Security modelWhat Shortspan protects against, what it does not, and where the trust boundaries actually sit.
- EncryptionEnvelope encryption, the per-organization master key, the root key that wraps it, and how rotation works.
- Roles and permissionsThe four roles, how a permission decision is reached, and every gate a request passes through.
- Reporting a vulnerabilityHow to report a security issue, what is in scope, and what to expect after you send it.
Self-hosting
Running Shortspan on infrastructure you control.
- RequirementsThe runtime, database, queue, and mail transport a working deployment needs.
- InstallationFrom a clean host to a serving deployment, including the two keys you must generate before anyone signs up.
- Configuration referenceEvery environment variable the application reads, what it does, and what breaks when it is wrong.
- Running itQueue workers, the scheduler, health checks, backups, and the failure modes that are silent by default.
- UpgradingDeploying a new version safely, including the migrations that must run before traffic returns.
Reference
Tables to look things up in.
- Plans and limitsEvery limit and feature flag, and which tier unlocks it.
- Secret templatesThe nine typed secret shapes, their fields, and where each one is stored.
- Role capabilitiesA matrix of what each role may do on each resource.
- Error codesEvery error code the API returns, what causes it, and what to do about it.
- GlossaryThe terms this documentation uses, defined once.