Borealis Docs

Authentication and organisations

A valid identity is only the first check. Resource access also depends on organisation, permission, ownership, and account entitlement.

Sign in interactively

Use the Borealis app for browser sessions or borealis auth login for CLI access. The CLI uses OAuth with PKCE and stores its session through a supported operating-system credential store.

If you cancel or encounter a login error, follow the recovery instructions shown by the CLI. Do not copy browser session cookies into scripts.

Select the right organisation

Check the app’s selected organisation before creating resources. In the CLI, inspect borealis context show --json and use --organization ORGANISATION_ID when you need explicit selection.

For API integrations, X-Organization-Id selects authorised organisation context. It cannot be used to gain access to another organisation’s resources.

Request only needed permissions

Sandbox reads, writes, and execution have separate scopes, including borealis.sandboxes.read, borealis.sandboxes.write, and borealis.sandboxes.exec. Registries, templates, hosts, and billing have their own permission families.

An interactive CLI login does not automatically request every privileged management scope. An administrator may need to authorise additional host-management, service-principal, or billing operations. A broader token still does not override plan restrictions or resource ownership.

Use automation credentials carefully

Use a service principal where your organisation and permissions support it. Store credentials in your automation platform’s secret storage, rotate them according to your policy, and revoke access when the integration is retired.

Supply CLI access tokens through an environment variable or protected token file. Do not place credentials in source control, shared command history, or build output.

Keep API and MCP credentials separate: the services use different audiences. If a token works in one surface but not another, inspect the audience and granted scopes rather than repeatedly broadening permissions.