> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> List, fetch, and switch the workspaces your token can access.

export const ErrorTable = ({errors}) => <div className="gv-error-table" role="table" aria-label="Errors and fixes">
    <div className="gv-error-table__head" role="row">
      <span className="gv-error-table__col-head" role="columnheader">Error</span>
      <span className="gv-error-table__col-head" role="columnheader">Cause</span>
      <span className="gv-error-table__col-head" role="columnheader">Fix</span>
    </div>
    {errors.map((err, i) => <div className="gv-error-table__row" role="row" key={i}>
        <code className="gv-error-table__code" role="cell">{err.code}</code>
        <div className="gv-error-table__cause" role="cell">{err.cause}</div>
        <div className="gv-error-table__fix" role="cell">{err.fix}</div>
      </div>)}
  </div>;

export const ExpectedOutput = ({caption = "Expected output", children}) => <div className="gv-output">
    <div className="gv-output__label">
      <svg className="gv-output__icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <polyline points="15 10 20 15 15 20" />
        <path d="M4 4v7a4 4 0 0 0 4 4h12" />
      </svg>
      <span>{caption}</span>
    </div>
    <div className="gv-output__body">{children}</div>
  </div>;

export const APIBadge = ({method = "GET", path, scope}) => {
  const m = method.toUpperCase();
  return <span className="gv-api-badge">
      <span className={`gv-api-badge__method gv-api-badge__method--${m.toLowerCase()}`}>
        {m}
      </span>
      <code className="gv-api-badge__path">{path}</code>
      {scope && <span className="gv-api-badge__scope">
          <span className="gv-api-badge__scope-label">scope</span>
          <code>{scope}</code>
        </span>}
    </span>;
};

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="RESOURCE" />

A workspace is the top-level tenant in gavAI. Every resource — pages, agents, tokens, secrets, deployments, domains — lives inside one workspace and is addressed by its slug. The Workspaces resource lets you list the workspaces a token can reach, resolve the current default, and switch the active context on OAuth sessions. By the end of this page you will know which endpoints exist and how switching differs between key types.

## A first call

<APIBadge method="GET" path="/v1/workspaces" scope="workspaces:read" />

```bash theme={null}
curl https://api.gavai.app/v1/workspaces \
  -H "Authorization: Bearer gak_live_xxxxxxxxxxxxx"
```

<ExpectedOutput>
  ```json theme={null}
  {
    "workspaces": [
      { "id": "ws_01H...", "slug": "acme", "name": "Acme Corp" }
    ],
    "next_cursor": null
  }
  ```
</ExpectedOutput>

Workspaces are returned as cursor-paginated `data` — see [Pagination](/api-reference/pagination) for the iteration protocol.

## Endpoints

<APIBadge method="GET" path="/v1/workspaces" scope="workspaces:read" />

List all workspaces accessible to this token.

<APIBadge method="GET" path="/v1/workspaces/current" scope="workspaces:read" />

Resolve the default workspace for this token or session.

<APIBadge method="GET" path="/v1/workspaces/{slug}" scope="workspaces:read" />

Fetch a single workspace by slug.

<APIBadge method="POST" path="/v1/workspaces/{slug}/switch" scope="workspaces:write" />

Switch the active workspace context (OAuth sessions only).

## Default workspace resolution

| Principal           | What `GET /v1/workspaces/current` returns                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| Workspace API key   | The workspace the key was minted against. Always the same.                                              |
| OAuth session token | The workspace active when the session was established, or the workspace last switched to via `/switch`. |

## Switching context

<APIBadge method="POST" path="/v1/workspaces/{slug}/switch" scope="workspaces:write" />

Switch applies only to OAuth session tokens. API keys are workspace-scoped at mint time and cannot be redirected — mint a new key against the target workspace instead.

The endpoint returns the workspace that is now active for the session:

<ExpectedOutput>
  ```json theme={null}
  {
    "workspace": { "id": "ws_01H...", "slug": "acme", "name": "Acme Corp" }
  }
  ```
</ExpectedOutput>

Common errors:

<ErrorTable
  errors={[
{ code: "403 workspace_forbidden", cause: "Session has no access to the target workspace.", fix: "Have an admin invite the user, or switch to a workspace the session can reach." },
{ code: "404 not_found", cause: "No workspace with that slug.", fix: "Verify the slug; list `/v1/workspaces` to see what is reachable." },
]}
/>

## Related

<Card title="API tokens" icon="key" href="/api-reference/resources/tokens">
  Create, rotate, and revoke workspace API keys.
</Card>