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

# List Workspaces

> List the tenancies this credential is allowed to work in

Returns every tenancy the presented credential may act in. An API key is pinned at
issue time and returns exactly one entry. An MCP OAuth connection returns whatever
its grant covers: one tenancy for a pinned grant, or the personal space plus every
team workspace the connected account can reach for an all-access grant.

Use a returned `selector` as the `X-Genviral-Workspace` header on later calls to run
that request in the named tenancy.

## Response

<ResponseField name="selector" type="string">
  The exact value to send in `X-Genviral-Workspace`: `personal`, or a workspace ID.
</ResponseField>

<ResponseField name="kind" type="string">
  `personal` or `workspace`.
</ResponseField>

<ResponseField name="name" type="string">
  Display name for the tenancy.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://www.genviral.io/api/partner/v1/workspaces \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Workspaces retrieved",
    "data": [
      {
        "selector": "personal",
        "kind": "personal",
        "name": "Personal space"
      },
      {
        "selector": "bbf64a28-a2fd-48f4-88ef-bf7480f18402",
        "kind": "workspace",
        "name": "Acme Studio"
      }
    ]
  }
  ```
</ResponseExample>

## Targeting a tenancy

Send the selector on any endpoint. The header may only narrow a credential to a
tenancy it already covers, never widen it.

```bash cURL theme={null}
curl --request GET \
  --url https://www.genviral.io/api/partner/v1/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Genviral-Workspace: bbf64a28-a2fd-48f4-88ef-bf7480f18402'
```

Omitting the header uses the credential's own default: its pinned tenancy, or the
personal space for an all-access MCP grant.

## Error Responses

* `401` - authentication failed
* `403` - `tenancy_not_granted`: the credential may not act in the named tenancy