Skip to content
Shortspan

Search documentation

Find a page by title, section, or summary.

API tokens and devices

Minting scoped tokens for automation, reviewing authorized CLI devices, and revoking either in a hurry.

API tokens

A token is a bearer credential: anything holding it can act as you, within its abilities and your role. shortspan login mints one automatically; for automation you mint one by hand.

bash
shortspan token list
shortspan token create ci-deploy --abilities secrets:read --abilities ssh:use
shortspan token revoke <token-id>

Or under API tokens in the console. Either way the token is displayed exactly once, at creation. There is no way to read it again - only a hash is stored.

Abilities

Abilities narrow what a token may do. They never widen it - a token with secrets:reveal held by a viewer still reveals nothing.

AbilityGrantsIn the default set

secrets:read

List secrets and inject them

yes

secrets:reveal

Print a secret value

no

secrets:write

Create, update, delete secrets

no

ssh:use

SSH sessions and remote commands

yes

db:use

Database credentials

yes

aws:inject

AWS credentials

yes

k8s:use

Kubeconfigs

yes

runbooks:execute

Run runbooks

yes

runbooks:manage

Create and edit runbooks

no

runbooks:approve

Approve an execution

no

access:request

Request temporary access

yes

access:manage

Approve and deny requests

no

audit:read

Read the audit log

no

Devices

Completing shortspan login registers a device: which machine, when it was authorized, from where, when it was last seen, and every command it has run since.

The device page is the fastest way to answer "what has this laptop been doing" - it lists the command history with timestamps and outcomes, not just the fact that the device exists.

Revoking a device kills its token immediately. There is no cached grace period; the next request from it fails.

Hygiene

  • One token per purpose. A single token shared between three pipelines cannot be revoked without breaking all three, which is how a token nobody trusts stays alive for years.

  • Name tokens after what uses them, not who made them. ci-deploy-api beats faizan-token-2.

  • Set an expiry when you can. A token that expires on its own is one fewer thing to remember.

  • Revoke the device when you replace a laptop, at the moment you replace it.

Token creation, imminent expiry, and revocation each send you a notification, so a token appearing that you did not create is visible rather than silent.

If a token leaks

  1. 1

    Revoke it

    From the console, or shortspan token revoke <id>. Effective on the next request.

  2. 2

    Read the audit log

    Filter by that token. Look at source addresses and timing - a token used from a place its owner has never been is the clearest signal there is.

  3. 3

    Rotate what it could reach

    Any secret it read, and any credential it brokered, should be considered exposed. Rotate at the source, not just in Shortspan.

  4. 4

    Narrow the replacement

    If the leaked token had more abilities than the job needed, the replacement is the moment to fix that.

Something here wrong or missing? Tell us.