Skip to main content

​
Authentication

rbtk supports three auth flows. Use the one that fits your environment. You can mix them — for example, rbtk auth login on your laptop and ROBOTICKS_API_KEY on your home server. The CLI picks the highest-priority configured source per invocation.

​
OAuth + keyring (local development)

The browser-based flow is the default for human use. It stores a refresh token in the OS keyring (macOS Keychain, GNOME Keyring, Windows Credential Manager) — never on disk.
If the browser cannot open (SSH session, headless), the CLI prints a URL and a one-time code:

​
Logout

​
API key (CI generic)

For any CI system that isn’t GitHub Actions, mint a project-scoped API key in the dashboard and inject it as an environment variable.

​
Mint a key

  1. Settings → API keys → New key
  2. Name it for the consumer (e.g., gitlab-ci-warehouse)
  3. Pick a scope:
    • Project — most common; key is bound to one project, cannot escape
    • Org admin — for org-wide automation; use sparingly
  4. Optionally set an expiry. Default is 90 days.
  5. Copy the displayed rbtk_sk_... value once — it is never shown again.

​
Use it

In CI:
Never commit an API key to version control. Use your CI’s secret store. Revoke immediately if leaked.

​
Rotate and revoke

Or Settings → API keys → ⋯ → Revoke in the dashboard.

​
GitHub OIDC (GitHub Actions)

GitHub Actions can mint short-lived OIDC tokens that the platform accepts in exchange for an ephemeral CLI access token. No long-lived secrets in your repo.

​
One-time setup

In the dashboard at Settings → GitHub OIDC, register your GitHub repo (or org) and set the subject claim policy:
The platform mints CLI tokens only for workflow runs whose sub claim matches a policy line.

​
In your workflow

rbtk auth oidc-from-github reads ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN (auto-injected by GitHub Actions), trades them for a CLI token via /auth/oidc/exchange, and caches the result in memory for the workflow’s lifetime. You get no secret rotation work and least-privilege out of the box.

​
Auth precedence

Per invocation, the CLI checks in order:
  1. --api-key flag (rare; mostly for one-off scripts)
  2. ROBOTICKS_API_KEY env var
  3. In-memory OIDC token from a prior rbtk auth oidc-from-github in the same process
  4. OS keyring entry from a prior rbtk auth login
The first match wins. rbtk auth status shows which source the current invocation would use.

​
Project-scoped vs org-admin

Default to project-scoped for CI. Reserve org-admin for human operators and audit tooling.

​
Troubleshooting

Run rbtk auth status. If the token is expired and there’s no refresh token, run rbtk auth login again. In CI, the API key may have been revoked — check the dashboard.
Your workflow ran on a ref that isn’t allowed by the subject claim policy. Either tighten the workflow’s run conditions or add the ref to the policy at Settings → GitHub OIDC.
Install python3-secretstorage and gnome-keyring, or set ROBOTICKS_API_KEY in the environment as an alternative.

​
Next

Context switching

Pick org and project per invocation.

CI/CD recipes

GitHub Actions, GitLab, Jenkins, CircleCI, BuildKite.