Authentication

curl -H "Authorization: Bearer $SHORTSPAN_TOKEN" \
     -H "Accept: application/json" \
     https://shortspan.dev/api/v1/auth/me

Tokens are issued by the device flow, by shortspan token create, or in the console under API tokens. They are shown once; only a hash is stored.

GET /api/v1/auth/me returns the authenticated user and the current token's abilities. It is the cheapest way to check that a token is live and correctly scoped.

Each token carries abilities that narrow what it may do. They never widen it - the role check runs regardless, so a token with secrets:reveal held by a viewer reveals nothing.

curl -X POST https://shortspan.dev/api/v1/tokens \
  -H "Authorization: Bearer $SHORTSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy",
    "abilities": ["secrets:read", "ssh:use"]
  }'

Omitting abilities grants the standard interactive set: secrets:read, ssh:use, db:use, aws:inject, k8s:use, runbooks:execute, access:request. Note that secrets:reveal is not among them.

The full list is in API tokens and devices.

For clients that cannot receive a redirect - a CLI, a TV, a headless tool. Two endpoints, both unauthenticated.

1. Request a code

curl -X POST https://shortspan.dev/api/v1/auth/device-code

{
  "data": {
    "device_code": "…",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://shortspan.dev/device",
    "expires_in": 600,
    "interval": 5
  }
}

2. Show the user code, and poll

Display user_code and verification_uri. The person opens the URL in a browser where they are signed in, checks that the code matches, and approves. Meanwhile, poll:

curl -X POST https://shortspan.dev/api/v1/auth/device-token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "…"}'

Codes live for ten minutes. Both the code and the poll are rate limited, per code and per IP, so a single honest login has its own budget while enumeration across many codes is bounded.

# Revoke the token making the request
curl -X DELETE https://shortspan.dev/api/v1/auth/token \
  -H "Authorization: Bearer $SHORTSPAN_TOKEN"

# Revoke another one you own
curl -X DELETE https://shortspan.dev/api/v1/tokens/{tokenId} \
  -H "Authorization: Bearer $SHORTSPAN_TOKEN"

Self-revocation remains available to suspended accounts. Losing access must never mean losing the ability to hand a credential back.