Marketplace / Docs / API Keys & CLI Auth

API Keys & CLI Auth

Generate API keys, authenticate the Snippbot CLI against the marketplace, and use those keys safely in CI.

Jump to section

How to generate API keys, authenticate the Snippbot CLI against the marketplace, and use those keys safely in CI.

Overview

The Singularity Marketplace supports two authentication modes:

  • Session login — interactive, uses your email and password to mint short-lived access + refresh tokens. Best for everyday CLI use on a trusted machine.
  • API key login — long-lived, single-string credential you generate from the dashboard. Best for CI, scripts, and machines where you can't type a password.

Both modes hit the same Authorization: Bearer ... header on registry requests. The CLI stores whichever credential you used in ~/.snippbot/marketplace_token.json (mode 0600 on Unix) and picks it back up on subsequent invocations.

Creating an API Key

API keys are generated from the Settings page of your publisher dashboard:

  1. Sign in at /login.
  2. Open /dashboard/settings.
  3. Scroll to the API Keys section.
  4. Enter a name (e.g. ci-publisher, laptop-2026) and click Create.
  5. Copy the key now. The full key is shown exactly once, in the green callout. After you dismiss it, only the prefix is visible.

The dashboard table for existing keys shows: name, key prefix, scopes, creation date, and last-used timestamp. You cannot retrieve the full secret of an existing key — if it's lost, revoke and re-create.

Under the hood the dashboard calls POST /api/v1/auth/keys with {"name": "...", "scopes": [...]} and returns the full key in the response body once.

Key Scopes

Each key carries a list of scopes. Today the dashboard creates keys with the default scope:

  • publish — allowed to publish package versions and manage your own packages.

The scope list is enforced on the registry side; the dashboard does not yet expose a multi-scope picker. Additional scopes for fine-grained CI permissions are planned — for now, treat keys as full-publisher credentials and scope them by which machine gets the key, not by what they can do.

Authenticating the CLI

Once you have a key string (looks like sk_...), authenticate the CLI:

snippbot marketplace login --api-key sk_your_key_here

The CLI validates the key against GET /api/v1/auth/whoami and, on success, writes a token file to ~/.snippbot/marketplace_token.json containing the API key, your publisher name, and the registry URL. From then on every marketplace command authenticates automatically.

You can also point the CLI at a key without storing it, by exporting an env var:

export SINGULARITY_API_KEY=sk_your_key_here
snippbot marketplace publish .

Resolution order when the CLI decides which credential to use:

  1. SINGULARITY_API_KEY environment variable.
  2. api_key value in ~/.snippbot/marketplace_token.json (set by login --api-key).
  3. singularity_api_key in your user config (snippbot config set ...).
  4. Session access token from marketplace_token.json (set by interactive login).

Email/password login uses the same command without the flag:

snippbot marketplace login --email [email protected]

You'll be prompted for the password securely.

Verifying Your Session

To confirm which publisher the CLI is acting as, run:

snippbot marketplace whoami

You'll see your publisher handle, display name, email-verified status, package count, and total installs. Use --json for a machine-readable version in scripts.

If you're not logged in, the CLI prints a Not logged in hint and exits without an error.

Logging Out

snippbot marketplace logout

This deletes ~/.snippbot/marketplace_token.json. Both session tokens and API keys stored in the file are cleared. Note that this does not revoke the API key on the server side — see Revoking a Key for that.

Using API Keys in CI/CD

In GitHub Actions, store the key as an encrypted secret and inject it via env:

- name: Publish to Singularity
  env:
    SINGULARITY_API_KEY: ${{ secrets.SINGULARITY_API_KEY }}
  run: snippbot marketplace publish .

Because the env var takes priority over the token file, you don't need to run marketplace login in CI — the publish command picks up the key automatically. Avoid writing the key to a token file in CI (don't run login --api-key there) since CI workspaces are often cached or shared and any persisted credential is a leak risk.

Revoking a Key

To revoke a key, return to /dashboard/settings, find the key in the API Keys list, and click Revoke. This hits DELETE /api/v1/auth/keys/{key_id} and immediately invalidates the key for all future requests.

Revoke a key whenever:

  • A machine that held it is decommissioned.
  • A team member with access to it leaves.
  • You suspect the key was logged, pasted into a shared chat, or committed to a repo.

After revoking, generate a new key with a fresh name and update any CI secrets that referenced the old one.

Security Notes

  • The full key is shown once. When the dashboard surfaces a newly created key, copy it immediately to wherever it needs to live (CI secret store, password manager). After closing the dialog only the prefix is visible.
  • The token file is 0600. On Unix the CLI writes marketplace_token.json with owner-only permissions. On Windows the file inherits its parent directory's ACL — protect ~/.snippbot/ accordingly.
  • last_used_at is your tripwire. A key that was last used at an unfamiliar time (or from CI you've since deleted) is a sign you should rotate.
  • Don't share keys across machines. Generate one per machine/CI so revoking a single key doesn't break everything else.
  • API key login bypasses email/password 2FA. Treat each key as a full credential and rotate on the same cadence you'd rotate a password.

CLI Reference

For the full list of flags and subcommands, see the Snippbot CLI reference.

Auth-related commands at a glance:

  • snippbot marketplace login [--email EMAIL] [--password PASSWORD] — interactive session login.
  • snippbot marketplace login --api-key KEY — log in with an API key.
  • snippbot marketplace logout — clear stored credentials locally.
  • snippbot marketplace whoami [--json] — show the active publisher.
  • snippbot marketplace register — create a new publisher account.