Skip to main content

​
Authentication

rbtk supports three auth flows. Use the one that fits your environment.
FlowWhere it shinesWhat it stores
OAuth + system keyringLocal developmentRefresh token in the OS keyring
ROBOTICKS_API_KEY env varAny CI, scheduled jobs, scriptsNothing — env-var only
GitHub OIDC exchangeGitHub ActionsEphemeral access token per workflow run
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. 
rbtk auth login

# 1. Browser opens to https://app.roboticks.io/cli/authorize?code=...
# 2. You approve the request
# 3. The CLI exchanges the code for an access + refresh token
# 4. Refresh token written to keyring

rbtk auth status
# Logged in as amir@roboticks.io
# Org:     acme (Team)
# Project: warehouse
# Token:   expires in 58m, auto-refreshing
If the browser cannot open (SSH session, headless), the CLI prints a URL and a one-time code: 
Open this URL on a device with a browser:
  https://app.roboticks.io/cli/authorize?code=GZHF-QXAQ
Then return here.

[waiting for approval... 5m]

​
Logout

rbtk auth logout
# Cleared refresh token from keyring

​
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

export ROBOTICKS_API_KEY=rbtk_sk_xx...
rbtk test list
In CI: 
variables:
  ROBOTICKS_API_KEY: $ROBOTICKS_API_KEY   # set as a masked CI variable
Never commit an API key to version control. Use your CI’s secret store. Revoke immediately if leaked.

​
Rotate and revoke

# List keys for the current project
rbtk auth keys list

# Revoke one
rbtk auth keys revoke rbtk_sk_xx... --confirm
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: 
repo:acme/warehouse:ref:refs/heads/main
repo:acme/warehouse:environment:production
The platform mints CLI tokens only for workflow runs whose sub claim matches a policy line.

​
In your workflow

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      id-token: write        # required for OIDC
      contents: read
    steps:
      - uses: actions/checkout@v4
      - run: pipx install roboticks-cli
      - run: rbtk auth oidc-from-github
      - run: rbtk test run --push ./
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

Project keyOrg admin key
Sees test resultsOne projectAll projects
Creates test runsOne projectAll projects
Manages billingNoYes
Manages membersNoYes
Rotates other keysNoYes
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.