Sign in and keys

Rehearsal has two kinds of identity. You sign in to the console with an account. Programs (the CLI, a script, an AI assistant, a CI job) use an API key. A key belongs to one project and has one level of access.

Your console accountCopy Anchor Link

On the hosted service, choose Create an account on the sign-in page, or sign in with Google.

On a server that your team runs, Create an account is there by default too. An account made that way starts a new organisation of its own. To work in a project that already exists, ask the operator to add you to it on the server:

rehearsal users add you@example.com --project <project_id>

The command asks for a password of 10 characters or more. With --no-password, the person signs in with Google only. An operator who does not want visitors to create accounts sets REHEARSAL_SIGNUP=closed. The sign-in page then has no Create an account link.

Sign in a terminalCopy Anchor Link

rehearsal login

The terminal shows a confirmation code and opens the console in your browser. The page shows the terminal's name, the address the request came from, and the workspace. Check that the code is the same in both places, then choose Approve.

Approval creates a new key with Build and evaluate access, named after your terminal. The key goes straight to the terminal and is saved in ~/.config/rehearsal/config.json, readable by your user only. The CLI, the Python client and the MCP server for AI assistants all read that file.

• Only an owner or an admin of the workspace can approve a terminal. If you are a member, ask one of them, or ask for a key.
• A sign-in request expires after 10 minutes.
• --url <address> chooses the server. Without it, the CLI uses REHEARSAL_URL, then the last server you signed in to, then the hosted service at https://rehearsalkit.xyz.
• --no-browser prints the link and does not open a browser.

rehearsal whoami shows which server, workspace and key the machine uses. rehearsal logout removes the saved key from the machine. It does not disable the key: to do that, revoke it.

Without a browserCopy Anchor Link

On a server or in CI, paste a key instead:

rehearsal login --with-key

The command asks for the key and hides what you paste. Or set two environment variables, which take precedence over a saved sign-in:

export REHEARSAL_URL=https://rehearsal.example.com
export REHEARSAL_API_KEY=<your_key>

Create a key in the consoleCopy Anchor Link

Open API keys. Give the key a name that says who or what uses it, and choose its access.

The console shows a key once. Copy it then. Rehearsal stores only a hash of the key, so nobody can show it to you again.

Give each person, pipeline and assistant its own key. Then you can revoke one without stopping the others.

A key looks like rh_1a2b3c4d_.... The eight characters after rh_ are its prefix: the console and rehearsal whoami show the prefix so that you can tell keys apart.

Send a key over HTTPCopy Anchor Link

Send the key in the Authorization header:

curl https://rehearsal.example.com/v1/me -H "Authorization: Bearer <your_key>"

{
  "project_id": "prj_7f4a9532b99af3d2",
  "key_id": "key_fce4d465bb875ab7",
  "scopes": ["write", "evaluator"],
  "project": "default",
  "organization": "Acme"
}

The output is shortened. The API calls the access levels scopes:

A request that needs a scope the key does not have gets status 403.

Revoke a keyCopy Anchor Link

Open API keys and revoke the key. It stops working at once, everywhere. Programs that used it get status 401.

Revoke a key when a person leaves, when a machine is lost, or when a key may have been seen by someone else. Then create a new one.

Keep keys safeCopy Anchor Link

• Do not paste a key into a chat with an AI assistant. Use rehearsal login.
• Do not put a key on a command line: it stays in the shell history. Use rehearsal login --with-key, or an environment variable from your secret store.
• Do not commit a key. Keys start with rh_, so a secret scanner can find them.