Stepshots logoStepshots

API Keys

Generate and manage Stepshots API keys to authenticate CLI and browser-extension uploads. Where to create a key, set STEPSHOTS_TOKEN, and use it in CI.

Overview

API keys let the Stepshots CLI and browser extension upload demos to your workspace without an interactive browser login. Reach for a key when you're:

  • Uploading from CI or another headless/automated environment
  • Uploading demos from the browser extension
  • Integrating with external tools and workflows

Generate an API Key

  1. Sign in to your Stepshots dashboard
  2. Open Settings
  3. Click Generate API Key
  4. Copy the key immediately

How Keys Work

  • Keys start with the oat_ prefix, so you can recognize them in CI logs and secret stores.
  • Stepshots stores only a SHA-256 hash of your key, never the plaintext. That's why it can't be shown again after creation.
  • Each account has one active API key. Generating a new key immediately replaces the previous one — any pipeline or extension still using the old key stops working. Treat "Generate API Key" as a rotation, and update your secrets in the same sitting.

Verify a Key

Check that a key is valid and see which account it belongs to:

bash
STEPSHOTS_TOKEN=oat_... stepshots whoami

whoami calls the server with your token and prints the account it resolves to, along with where the token came from (--token / STEPSHOTS_TOKEN, or your stored login). This is the fastest way to debug a failing CI upload — run it with the exact token your pipeline uses.

Token precedence

The CLI resolves credentials in this order:

  1. --token flag
  2. STEPSHOTS_TOKEN environment variable
  3. The token stored by stepshots login

So a locally logged-in machine and a CI runner with STEPSHOTS_TOKEN behave the same way — you never need login where a key is set.

Using Your API Key

CLI

Pass the key directly:

bash
stepshots upload output/my-demo.stepshot --token YOUR_API_KEY

Or set it as an environment variable (recommended):

bash
export STEPSHOTS_TOKEN=YOUR_API_KEY
stepshots upload output/my-demo.stepshot

In a CI pipeline, add --public to publish uploaded demos immediately instead of leaving them as private drafts:

bash
stepshots upload output/my-demo.stepshot --public

Browser Extension

  1. Open the Stepshots extension side panel
  2. Go to Settings
  3. Paste your Stepshots URL and API Key
  4. Save

The extension uses the key to upload recordings directly to your workspace.

Environment Variables

The CLI recognizes these environment variables:

Variable Description
STEPSHOTS_TOKEN API key for uploads in CI/headless environments. Optional interactively — the CLI falls back to your stepshots login token.
STEPSHOTS_SERVER Override the server URL (default: https://stepshots.com)
STEPSHOTS_CONFIG Path to the stepshots.config.json file (same as --config)
STEPSHOTS_PROFILE_DIR Persistent browser profile directory for authenticated recordings (same as --profile-dir)
CHROME_PATH Path to Chrome/Chromium binary (if not in the default location)

Using Keys in CI

Store the key as a secret in your CI provider (e.g. a GitHub Actions repository secret named STEPSHOTS_TOKEN) and expose it to the upload step as an environment variable. Never commit a key to the repository or echo it in logs.

For the full pipeline — validating configs, recording headlessly, drift detection with verify, and the ready-made GitHub Action — see CI Automation.

Security Best Practices

  • Scope by environment: use your personal login on your laptop and reserve the API key for CI and the extension, so revoking the key never locks you out locally.
  • Rotate after exposure: if a key lands in a log, a screenshot, or a shared terminal, generate a new one — rotation is instant and the old key dies with it.
  • Prefer secrets over env files: .env files get committed by accident; CI secret stores and password managers don't.

Revoking a Key

To revoke an API key, open Settings in the dashboard and delete the key. Any CLI or extension using that key will immediately lose upload access.

Generate a new key and update your CI secrets or extension settings.

Troubleshooting

Upload fails with 401 Unauthorized — the key was revoked or replaced by a newer one. Run STEPSHOTS_TOKEN=... stepshots whoami with the exact token from your secret store; if it fails, generate a fresh key and update the secret.

Not logged in error despite setting a key — the variable isn't reaching the CLI process. Confirm it's exported in the same shell (echo ${STEPSHOTS_TOKEN:+set}) or passed into the CI step's env: block.

Extension uploads fail after key rotation — the extension keeps its own copy of the key. Open the side panel Settings and paste the new key there too.

Navigation