Authentication

Setup

Install Rebase Toolkit and authenticate this computer:

uv pip install "rebase-toolkit @ git+https://github.com/rebase-energy/rebase-toolkit.git"
rebase setup

pip install rebase-toolkit also works, but the PyPI release can lag the GitHub version.

rebase setup signs you in with Google or GitHub, creates or selects a workspace, and writes a local auth session plus workspace profile on this computer. The SDK reads that session automatically when you use rb.project(...), rb.get_function(...), rb.get_workflow(...), or rb.workspace().

The hosted Rebase API URL is built into rebase-toolkit. Users should not set an API URL for normal usage.

Rebase is invite-only. Signing in requires a platform invite or a pending workspace invite, and creating a workspace requires a platform invite. Without one, the API answers 403 with your profile has not been invited.

Bearer Tokens

The SDK sends the stored user session access token as a bearer token. The health and setup-config API routes are public. Workspace, project, function, workflow, model, endpoint management, and run API routes require a valid bearer token when auth is enabled.

The API resolves that user token to a Rebase profile and one active workspace membership. Use X-Rebase-Workspace only when the same user has access to multiple workspaces and needs to target a non-default workspace.

Workspace Invites

Workspace owners can invite collaborators by email address or GitHub username:

rebase workspace invite davide@rebase.energy --role Developer
rebase workspace invite davide-github --role Developer

List active members and pending invites:

rebase workspace members

Roles are Viewer, Developer, Admin, and Owner. A pending invite becomes a workspace membership when the invited user signs in with a matching email address or GitHub username.

API Keys

API keys are separate from the normal user sign-in flow. They are intended for direct API access and agent/service use cases where an interactive Google or GitHub sign-in is not appropriate.

API key secrets start with rb_. The service stores only key hashes and shows only the key prefix after creation. API keys are scoped to a workspace, and may also be scoped to a project and permission set.

Create an agent key:

rebase api-key create notebook

The default agent key grants read access to workspace metadata, projects, functions, workflows, models, and runs, plus endpoint read and execute permissions. The command prints the one-time secret. Store it securely; it cannot be retrieved again.

List and revoke keys:

rebase api-key list
rebase api-key revoke <id-or-prefix-or-name>

For direct API-key access, pass the key explicitly to the client:

import rebase as rb

client = rb.Client(api_key="rb_...")
print(client.get_workspace())

Only the key hash is stored by the service.

Endpoint Auth

Endpoints choose their invocation auth separately from endpoint management:

Use auth="api_key" for agents and service-to-service calls. Use auth="workspace" when signed-in users should call the endpoint through rebase endpoint invoke or the SDK's normal profile credentials.

Local Development

The Toolkit API can run with auth disabled. In that mode, requests use the configured default workspace and no bearer token is required.

Workspace Isolation

Every authenticated request resolves to a workspace. For user auth, the workspace comes from the selected workspace membership. For API keys, it comes from the key record.

Every API key has:

If a caller requests a project, function, workflow, model, endpoint, version, or run outside its workspace, the API returns 404.

SDK Configuration

The SDK reads the selected local profile:

import rebase as rb

project = rb.project("energy-forecasting")

One sign-in reaches every workspace you belong to, so you do not need a separate profile per workspace.

Workspace Profiles

List the workspaces you belong to:

rebase workspace list

Switch the active workspace (the current profile and sign-in are kept):

rebase workspace switch acme

Profiles are for a separate identity or a different API URL, not for separate workspaces. Create one with:

rebase setup --profile prod

List profiles and switch between identities:

rebase profile list
rebase profile switch prod

Repository Workspace Marker

A repository can pin itself to a workspace with a checked-in marker file, .rebase/config.json:

{
  "workspace": "<workspace-id>"
}

The SDK and CLI search from the working directory up through its parents for the nearest marker (the global ~/.rebase/config.json is not a marker — it holds your profiles). When one is found, its workspace overrides the globally active profile's. Full precedence, highest first:

1. rb.Client(workspace_id=...) passed explicitly,
2. the repository marker,
3. the active profile.

The marker pins the workspace, not credentials: the workspace travels as one request header, and your user session already reaches every workspace you belong to. That is what makes the file safe to commit — teammates each authenticate with their own credentials, but everyone in the checkout addresses the same workspace, with no second profile or sign-in. An API key is different: it is bound to its own workspace, so the marker cannot redirect it.

Be aware of the flip side: running the CLI inside a marked repository silently targets the marker's workspace, not the one rebase workspace shows as globally active. When resources seem to be missing, check for a marker first.

To make the marker's workspace the globally active one as well, run this inside the repository:

rebase activate

A profile that already holds that workspace becomes the default; otherwise the active profile's selection moves to it, checked against your memberships like rebase workspace switch. rebase init writes the marker and leaves the active workspace alone; rebase activate is the other half.