Workspaces

One login can own several workspaces. Each workspace has its own agents, phone numbers, API keys and balance. Calls, billing and keys in one workspace stay there.

Your first workspace is the one Rymi created when you signed up. It keeps the free monthly credit on the free plan. A workspace you create later does not get that credit. You can own at most 20 workspaces.

Switch in Studio

1. Open the account menu at the bottom of the sidebar.
2. Under Workspaces, click the workspace you want. Studio reloads on that workspace.
3. To add one, click New workspace, type a name (up to 80 characters) and click Create. The page reloads into the empty workspace.

The menu lists a workspace only when the API is serving GET /v1/workspaces. If that section is missing, this account is still on its single workspace and nothing else changes.

Studio remembers the choice in this browser. If you lose access to it, the next request gets 403 with code workspace_forbidden, Studio clears the choice and sends you back to your default workspace. It does not sign you out.

An admin who is impersonating a tenant stays in that tenant. Studio does not send a workspace switch during impersonation.

Switch on the API

Send the workspace id in the Rymi-Workspace header on any /v1 request:

GET /v1/agents
Rymi-Workspace: 7c9e6679-7425-40de-944b-e07fc1f90ae7

The request then runs in that workspace. Omit the header and the request stays in the workspace the credential already belongs to.

Who may name another workspace:

Credential	May switch to
Signed-in user (JWT)	A workspace they belong to
Secret key	A client workspace of the key's own workspace
Publishable key	Nowhere. The header is rejected.
Impersonation token	Nowhere. The header is rejected.

A workspace you cannot reach, and a workspace id that does not exist, both answer the same way: 403 with code workspace_forbidden. The body does not say which case it was.

List, create and rename workspaces with /v1/workspaces.

SDK and MCP

In @rymi/node, pass workspace or set RYMI_WORKSPACE. The client sends Rymi-Workspace on every call. rymi.workspaces lists, creates and updates workspaces. See the API reference for the methods.

The local MCP server reads RYMI_WORKSPACE the same way, because it uses the Node SDK. It also has list_workspaces and create_workspace. create_workspace makes a workspace with no free monthly credit.

On the hosted MCP endpoint, send Rymi-Workspace on the HTTP request. The server forwards that header with the tool calls.