Skip to content

Guides

Authentication and Organizations

Every call needs two things:

  • A Chainguard token for the sessions service.
  • An organization ID (the “instance”) that says where sandboxes live.

Simple Chainguard Sandbox SDK uses the Workspaces libraries’ login and organization handling, so there’s nothing sandbox-specific to set up.

By default the libraries log in through your browser, the same way chainctl does. chainctl itself isn’t needed:

  1. First call: with no saved login, the library opens the Chainguard login page (GitHub, Google, GitLab, or your organization’s identity provider) and waits for the redirect back to a local port.
  2. Saving: the refresh token is saved to login.json (mode 0600) in your user config directory. All four libraries share it.
  3. Later calls: the library mints one-hour tokens from the saved login without a browser.

How long a login lasts:

  • The refresh token is valid for 20 hours and is replaced on every use, so a login lasts as long as it’s used at least once every 20 hours.
  • When it expires, the next call opens the browser again. Approve it and the call continues. To renew ahead of time, run the login command again.

Log in ahead of time with any library’s CLI. Add github, google-oauth2 or gitlab to skip the provider choice:

uv run chainguard-sandbox login
uv run chainguard-sandbox whoami # who you're logged in as, and the token's expiry
# run these in a project with the package added, or in a clone of the repository from its python/ directory

There are three ways; the first one set wins.

  1. In code: instance= (Python), instance (TypeScript), Instance (Go), instance (Rust), on Sandbox.create, Sandbox.connect, Sandbox.list, or the library Client.
  2. Environment variable: export CHAINCTL_SANDBOX_INSTANCE=XXXXXX.
  3. Auto-detection: used when neither is set:
    • the library lists the organizations your identity belongs to;
    • with exactly one, it uses it;
    • with several, it fails with a message listing their IDs and names;
    • with none, it fails with “your identity belongs to no Chainguard organization”.

Turn auto-detection off with CHAINGUARD_SANDBOX_NO_DETECT_INSTANCE=1, or in code: detect_instance=False on the Python Client, detectInstance: false on the TypeScript Client, NoDetectInstance: true in Go Options, no_detect_instance: true in Rust workspaces::Options. When no organization can be found, the error lists all three ways and how to look up the IDs.

When detection runs:

  • Go, Python and Rust: when the client is created, so in Sandbox.create / connect / list.
  • TypeScript: on the first call that needs the organization, then remembered.
  • Cost: one extra request, about 0.3 s. Setting the organization explicitly skips it.

Listing organization IDs:

Command In code
Python uv run chainguard-sandbox orgs from chainguard_sandbox import list_organizations
TypeScript bun run chainguard-sandbox orgs import { listOrganizations } from "chainguard-sandbox-sdk"
Go go run github.com/sandboxing-dev/chainguard-sandbox-sdk/go/cmd/chainguard-sandbox@latest orgs sandbox.ListOrganizations(ctx)
Rust chainguard-sandbox orgs (after cargo install) chainguard_sandbox::list_organizations()
chainctl chainctl iam organizations list —

In a clone of the repository the CLI runs from each language’s directory: uv run chainguard-sandbox orgs from python/, bun bin/chainguard-sandbox.ts orgs from typescript/ (after bun install), go run ./cmd/chainguard-sandbox orgs from go/, and cargo run --bin chainguard-sandbox -- orgs from rust/.

How Detection Works, and What the Login Covers

Section titled “How Detection Works, and What the Login Covers”

Organizations aren’t part of the sessions service. They live in Chainguard’s account API (IAM), a different service at https://console-api.enforce.dev. That has two consequences:

  1. A different API call. The libraries list organizations with GET https://console-api.enforce.dev/iam/v1/groups?uidp.in_root=true. Organizations are the root groups your identity can see. This is the same API chainctl iam organizations list uses.
  2. A different token.
    • Audiences: every Chainguard token names the services it’s for (its audience). A sessions token (https://sessions.chainbox.dev) is refused by the account API, and the reverse.
    • What the login asks for: the browser login lists the audiences it wants, and the saved refresh token can then mint tokens for any of them. The libraries’ login asks for two: https://sessions.chainbox.dev and https://console-api.enforce.dev. (chainctl asks for all of Chainguard’s services.)
    • Two tokens: sandbox calls use a sessions token, and auto-detection uses an account-API token. Both are minted from the same saved login.

What the account-API audience allows.

  • The token’s power: an account-API token acts as you, with your Chainguard roles. Like a chainctl login, it could do anything your roles allow in the account API, not just list organizations.
  • What the libraries do with it: they only read the list of organizations.
  • Keeping it out of the login: set CHAINGUARD_SANDBOX_LOGIN_AUDIENCES=https://sessions.chainbox.dev before logging in. Auto-detection then can’t work, so set the organization in code or with CHAINCTL_SANDBOX_INSTANCE.

Logins made before auto-detection existed cover only the sessions audience.

  • Sandbox calls keep working with them.
  • Auto-detection needs one new login to add the audience. With CHAINGUARD_SANDBOX_NO_BROWSER=1 it fails with “the saved login doesn’t cover https://console-api.enforce.dev; log in again”; otherwise it opens the browser.
  • The old login isn’t deleted just because it lacks an audience. It’s only forgotten when it has expired or is refused for an audience it covers.

Other token sources:

  • chainctl: with CHAINGUARD_SANDBOX_AUTH=chainctl, detection uses chainctl auth token --audience https://console-api.enforce.dev.
  • A fixed token: with CHAINCTL_AUTH_TOKEN or a custom token source, detection is skipped unless you also pass an account-API token source: platform_token_source= (Python), platformTokenSource (TypeScript), PlatformTokenSource (Go), platform_token_source (Rust). Otherwise set the organization explicitly.

Sandboxes can be created only in an organization where Workspaces is turned on. A new organization starts with it off, and create then fails with WorkspacesNotEnabledError (Go: ErrNotEnabled, Rust: Error::NotEnabled), carrying the service’s message “this organization is not entitled to Chainguard Workspaces”.

Turning it on takes three things, done once by an organization owner:

  1. Accept the terms. Workspaces is offered under the Secured Platform Terms and the Master Service and License Agreement. Turning it on also involves the Code Analysis Terms (the same switch turns on Chainguard Checks), and the Terms of Service and Data Privacy Agreement that linking GitHub requires.
  2. Link a GitHub account to the organization: your own user, or a GitHub organization you own. The service refuses to turn Workspaces on without one. The Chainguard GitHub App must be installed on the account, and you authorize the link in your browser.
  3. Turn the feature on. The organization gets its plan’s allowance (on the Starter plan: one sandbox per user and three in the organization at a time).

From the command line, chainguard-sandbox status shows where an organization stands and chainguard-sandbox enable does all three, asking before it accepts anything (see the Quickstart). From code:

from chainguard_sandbox import enable_workspaces, workspaces_status
st = workspaces_status() # reads; changes nothing
if not st.ready:
for doc in st.missing_terms: # show these to the person, and get their agreement
print(doc.label, doc.url)
st = enable_workspaces(accept_terms=True) # only once they have agreed
Python TypeScript Go Rust
Read the setup workspaces_status() workspacesStatus() sandbox.Status(ctx, nil) workspaces_status(&SetupOptions)
Turn it on enable_workspaces(accept_terms=True) enableWorkspaces({ acceptTerms: true }) sandbox.Enable(ctx, &sandbox.SetupOptions{AcceptTerms: true}) enable_workspaces(&SetupOptions { accept_terms: true, .. })
Result WorkspacesStatus: .ready, .enabled, .missing_terms, .github_accounts, .plan, .max_sandboxes, .max_sandboxes_per_user the same, in camelCase *WorkspacesStatus, with Ready() WorkspacesStatus, with ready()
Organization instance= instance SetupOptions.Instance instance
GitHub account to link github_account= githubAccount SetupOptions.GitHubAccount github_account
Port for GitHub’s redirect github_port= (8989) githubPort SetupOptions.GitHubPort github_port
Never open a browser open_browser=False openBrowser: false SetupOptions.NoBrowser no_browser: true
  • Accepting terms is explicit. Without accept_terms / acceptTerms / AcceptTerms, an organization with unaccepted terms gets TermsNotAcceptedError (Go: *TermsNotAcceptedError, Rust: Error::TermsNotAccepted), which lists the documents with their URLs. Nothing is accepted or changed. Pass the flag only when the person running your program has read and agreed to them: it is a legal act on the organization’s behalf.
  • The GitHub step needs a person. enable opens a browser on GitHub and waits (up to 10 minutes) for you to choose the account and authorize. Only an authorization code passes through your machine; the SDK never holds a GitHub token. If the organization already has an account linked, this step is skipped.
  • The app must be installed first. If the Chainguard GitHub App isn’t on the account, enable fails with GitHubAppNotInstalledError (Go: *GitHubAppNotInstalledError, Rust: Error::GitHubAppNotInstalled), which carries the install page. Install it and call enable again; the CLI does this loop for you.
  • Without a browser, enable fails with GitHubLinkRequiredError instead of waiting.
  • One Chainguard organization per GitHub account. Linking an account that is linked elsewhere fails.
  • It is safe to repeat. If Workspaces is already on and the terms are accepted, nothing is sent.
  • Checks comes with it. The same switch turns on Chainguard Checks.
  • Owner role. All three steps need it, and you must own the GitHub account. Members without the role can still read the status.
  • Not covered: creating the account and the organization (use the Console).

The calls behind these are listed in Protocol: Authentication and Organizations.

Variable Effect
CHAINCTL_SANDBOX_INSTANCE The organization ID (overrides auto-detection)
CHAINGUARD_SANDBOX_NO_DETECT_INSTANCE=1 Never auto-detect the organization
CHAINCTL_AUTH_TOKEN Use this sessions token as-is (audience https://sessions.chainbox.dev)
CHAINGUARD_SANDBOX_NO_BROWSER=1 Never open a browser: fail with a “login required” error instead. For scripts and CI
CHAINGUARD_SANDBOX_SOCIAL_LOGIN Preselect the login provider (github, google-oauth2, gitlab)
CHAINGUARD_SANDBOX_LOGIN_AUDIENCES Comma-separated audiences a new login asks for. Default: sessions + account API
CHAINGUARD_SANDBOX_AUTH=chainctl Mint tokens with an installed, logged-in chainctl instead
CHAINGUARD_SANDBOX_LOGIN_FILE Use another login file

The libraries also support Chainguard assumable identities: a CI job trades its OIDC token (GitHub Actions, GitLab, Kubernetes, …) for a Chainguard token. See IdentityExchange in the SDK’s READMEs. Starter organizations can’t create identities, so on that plan, unattended use needs a saved login or a token. In CI, set the organization explicitly; detection would need a second, account-API token.