---
title: "Rotate the session into another workspace"
method: POST
path: "/auth/switch-organization"
---

# Rotate the session into another workspace

`POST /auth/switch-organization`

## Request

- Base URL: `https://api.caveman.so/api/v1`
- URL: `https://api.caveman.so/api/v1/auth/switch-organization`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/api/v1/oauth/authorize`
    - Token URL: `/api/v1/oauth/token` scopes: `org:read`
  - HTTP bearer
  - API key in cookie `cave_access`
  - API key in cookie `__Secure-cave_identity.session_token`

POST /api/v1/auth/switch-organization on the Caveman Cloud control plane. Requires the org:read scope. Not exposed to autonomous agents: Moves the caller across the organization boundary. A project-scoped agent session must never leave its tenant.

## Headers

- `x-cave-csrf` 'ui'

## Request body

- object
  - `organization_id` string, uuid, required

## Response `200`

Session rotated into the selected active membership.

- AuthResponse
  - `user` object, required
    - `id` string, uuid, required
    - `email` string, email, required
    - `name` string, nullable
    - `organization_id` string, uuid, required
    - `role` 'owner' | 'admin' | 'engineer' | 'viewer' | 'billing', required
  - `access_token` string: Returned only to non-browser bearer clients; browser clients receive an HttpOnly cookie.
  - `refresh_token` string: Returned only to non-browser bearer clients; browser clients receive an HttpOnly cookie.

## Other responses

- `400`: Malformed target organization id or JSON body.
- `401`: Authentication required or the bound session is no longer valid.
- `403`: Target organization is not an active membership of the authenticated user, or browser CSRF header is missing. cave_sso_required when the target organization requires single sign-on of this non-owner member.
- `500`: Session rotation or token signing failed; no replacement credentials are returned.
- `2XX`: Successful response. Exact status depends on synchronous or durable delivery outcome.
- `4XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `5XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.

---

[API](https://skmtc.dev/caveman/apis/caveman-cloud-api.md) - [All operations](https://skmtc.dev/caveman/apis/caveman-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/caveman/apis/caveman-cloud-api/revisions/508312d01cfc?raw)