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.
Tokens
Section titled “Tokens”| 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.
Browser Login
Section titled “Browser Login”When there’s no saved login, or it has expired, the SDK logs in through the browser:
-
Listen: start an HTTP server on
127.0.0.1at a random port. -
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) -
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). -
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.
Refreshing a Token
Section titled “Refreshing a Token”POST https://issuer.enforce.dev/sts/exchange_refresh_token ?aud=https://sessions.chainbox.devAuthorization: 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.
Choosing the Organization
Section titled “Choosing the Organization”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=trueAuthorization: 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.
Enabling Workspaces
Section titled “Enabling Workspaces”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.
