Skip to content

Protocol

Authentication and Organizations

The Sessions API takes a Chainguard token as a bearer token. The SDKs get it from a saved browser login, over plain HTTPS to Chainguard’s token service, and, when you haven’t named an organization, ask Chainguard’s account API which one to use. Options and environment variables are on the Authentication and Organizations guide; this page is the wire view.

Token Audience Used for
Sessions token https://sessions.chainbox.dev every gRPC call: authorization: Bearer <token>
Account API token https://console-api.enforce.dev the organization lookup only
Refresh token — minting both of the above; saved in login.json

Both access tokens are Chainguard JWTs, minted from the same saved refresh token. Each is reused until a minute before it expires.

When there’s no saved login, or it has expired, the SDK logs in through the browser:

  1. Listen: start an HTTP server on 127.0.0.1 at a random port.

  2. Open the browser at:

    https://issuer.enforce.dev/oauth
    ?client_id=auth0
    &connection=<github | google-oauth2 | gitlab> (optional; omitted, the page asks)
    &audience=https://sessions.chainbox.dev,https://console-api.enforce.dev
    &create_refresh_token=true
    &refresh_token_rotation=true
    &skip_registration=true
    &exit=redirect
    &redirect=http://localhost:<port>/callback?token=true&error=true (URL-encoded)
  3. Callback: after you log in, the issuer redirects to http://localhost:<port>/callback?token=<JWT>&refresh_token=<refresh token>, or, on failure, ?error=<message>&status_code=<n> (404: no Chainguard account).

  4. Finish: the SDK answers with a redirect to / (so the tokens leave the address bar), shows a “login complete” page, stops the server, and saves the refresh token.

POST https://issuer.enforce.dev/sts/exchange_refresh_token
?aud=https://sessions.chainbox.dev
Authorization: Bearer <refresh token>
{
"token": { "token": "<access token for the audience>" },
"refreshToken": { "token": "<a new refresh token>" }
}
  • The audience is a query parameter. In a JSON body it’s ignored and the call fails with 400 Audience must be specified.
  • Rotation: every refresh returns a new refresh token and spends the old one. The SDK saves the new one at once, under a lock shared by all processes that use the same login file.
  • Expiry: a refresh token is valid for 20 hours from when it was issued, so a login lasts as long as it’s used at least once every 20 hours. An expired one is refused with HTTP 400 invalid refresh token: refresh token expired at … (not 401 or 403); the SDK treats that as an expired login and logs in again.

Every Sessions call is scoped to instances/{organization ID}. The SDK takes the ID from the instance option, then $CHAINCTL_SANDBOX_INSTANCE; failing both, it asks the account API:

GET https://console-api.enforce.dev/iam/v1/groups?uidp.in_root=true
Authorization: Bearer <account API token>
Accept: application/json
{
"items": [
{ "id": "XXXXXX", "name": "my-org" }
]
}

The response’s root groups (an id without a /) are the organizations you belong to. With exactly one, the SDK uses it; with none or several, it stops with an error that lists them.

Whether an organization can create sessions is decided by Chainguard’s platform API (https://console-api.enforce.dev), not by the Sessions service. These are plain HTTPS calls with a token for the platform audience, the same one that lists organizations. chainctl develop init makes the same calls over gRPC.

Step Call Notes
Read accepted terms GET /iam/v1/terms/{org} Returns items[], each with a docId, who accepted it and when
Accept terms POST /iam/v1/terms/{org} with {"documentIds": [...]} Owner role. Workspaces requires secure-platform-terms.v1 and msla.v1; Checks adds code-analysis-terms.v1, and linking GitHub adds guardener-tos.v1 and sfdpa.v1
List linked GitHub accounts GET /guardener/v1alpha1/githubAssociations/{org} Returns organizations[], each with the GitHub login
Start a GitHub authorization GET /guardener/v1alpha1/githubAssociations:begin Returns the Chainguard GitHub App’s OAuth clientId and a signed state
Authorize with GitHub Browser: https://github.com/login/oauth/authorize with client_id, state, a PKCE code_challenge (S256), prompt=select_account and redirect_uri=http://127.0.0.1:8989/callback GitHub redirects to the loopback port with a code. Another free port works
Link the account POST /guardener/v1alpha1/githubAssociations/{org}:link with {"code", "redirectUri", "codeVerifier", "state", "organization"} Owner role, and ownership of the GitHub account. organization is optional: without it, the authorizing user is linked. The service exchanges the code itself
Turn the feature on POST /entitlements/v1alpha1/features/{org}:enableSandbox with {} Owner role. Turns on Checks and Workspaces with the plan’s allowance. Refused until a GitHub account is linked
Read the entitlement GET /entitlements/v2beta1/organizationEntitlements?parent={org} The PRODUCT_SANDBOX_WORKSPACES product has state STATE_ACTIVE when on, and limits such as “concurrent workspaces per user”
{
"plan": { "id": "starter", "displayName": "Starter" },
"products": [
{
"product": "PRODUCT_SANDBOX_WORKSPACES",
"state": "STATE_ACTIVE",
"limits": [
{ "displayName": "concurrent workspaces", "max": "3", "used": "0" },
{ "displayName": "concurrent workspaces per user", "max": "1", "used": "0" }
]
}
]
}

A call refused because terms are missing answers with a details entry listing the missing documents (id, label, url). While Workspaces is off, the Sessions service answers CreateSession with PERMISSION_DENIED and the message “this organization is not entitled to Chainguard Workspaces”.

Verified against the live service: the read calls, starting a GitHub authorization, accepting terms, and the refusal enableSandbox gives while no GitHub account is linked (“the organization must link a GitHub organization through the Chainguard GitHub App first”). The link call and a successful enableSandbox are implemented from the API definitions in chainctl 0.2.398 and Chainguard’s published SDK (chainguard.dev/sdk/githubflow), and tested against a stand-in server.