# List organizations the caller can access

### get/beta/v1/organizations

Returns every organization the authenticated user / API key can act in, ordered with the primary (default-fallback) org first. Use this to discover valid `org_id` values to pass into other beta tools — required for users who belong to multiple orgs and want to scope a particular call to a non-primary org.

### Responses

#### 200
- **OK**  
  - Content-Type: application/json
  - **Structure**:
    ```json
    [
      {
        "id": "string",
        "name": "string",
        "domain": "string | null",
        "role": "string",
        "kind": "string",
        "is_primary": "boolean",
        "denied_permissions": [
          "string"
        ]
      }
    ]
    ```

#### 400
- **Bad request**  
  - Content-Type: application/json

#### 401
- **Unauthorized**  
  - Content-Type: application/json

#### 403
- **Forbidden**  
  - Content-Type: application/json

#### 404
- **Not found**  
  - Content-Type: application/json

#### 405
- **Method not allowed**  
  - Content-Type: application/json

#### 409
- **Conflict**  
  - Content-Type: application/json

#### 500
- **Internal server error**  
  - Content-Type: application/json

### Get an organization's management details

### get/beta/v1/organizations/{org_id}

Returns the org-management view of a single organization: name, domain, primary address, deactivation flag, and created_at.

### Path parameters
- **org_id**: string (uuid) - Required

### Responses

#### 200
- **OK**  
  - Content-Type: application/json
  - **Structure**:
    ```json
    {
      "id": "string",
      "name": "string",
      "domain": "string | null",
      "created_at": "string | date-time",
      "primary_address": {
        "id": "string",
        "line1": "string",
        "line2": "string | null",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string"
      }
    }
    ```

#### 400
- **Bad request**  
  - Content-Type: application/json

#### 401
- **Unauthorized**  
  - Content-Type: application/json

#### 403
- **Forbidden**  
  - Content-Type: application/json

#### 404
- **Not found**  
  - Content-Type: application/json

#### 405
- **Method not allowed**  
  - Content-Type: application/json

#### 409
- **Conflict**  
  - Content-Type: application/json

#### 500
- **Internal server error**  
  - Content-Type: application/json

### Update an organization's management details

### patch/beta/v1/organizations/{org_id}

Partial-update: every field is optional. Send only the fields you want to change.

### Path parameters
- **org_id**: string (uuid) - Required

### Body
- **application/json**  
  - **Structure**:
    ```json
    {
      "name": "string | min: 1 | optional",
      "domain": "string | min: 1 | null | optional",
      "primary_address": { 
        ...  
      }
    }
    ```

### Responses

#### 200
- **OK**  
  - Content-Type: application/json

#### 400
- **Bad request**  
  - Content-Type: application/json

#### 401
- **Unauthorized**  
  - Content-Type: application/json

#### 403
- **Forbidden**  
  - Content-Type: application/json

#### 404
- **Not found**  
  - Content-Type: application/json

#### 405
- **Method not allowed**  
  - Content-Type: application/json

#### 409
- **Conflict**  
  - Content-Type: application/json

#### 422
- **Unprocessable Content**  
  - Content-Type: application/json

#### 500
- **Internal server error**  
  - Content-Type: application/json

### Deactivate an organization

### post/beta/v1/organizations/{org_id}/deactivate

Soft-disables the organization: it stops appearing in `list_organizations` results and members lose access.

### Path parameters
- **org_id**: string (uuid) - Required

### Responses

#### 204
- **No Content**  
  ```
  No content
  ```  
#### 400
- **Bad request**  
  - Content-Type: application/json

#### 401
- **Unauthorized**  
  - Content-Type: application/json

#### 403
- **Forbidden**  
  - Content-Type: application/json

#### 404
- **Not found**  
  - Content-Type: application/json

#### 405
- **Method not allowed**  
  - Content-Type: application/json

#### 409
- **Conflict**  
  - Content-Type: application/json

#### 500
- **Internal server error**  
  - Content-Type: application/json

### Example Requests

#### Example for Listing Organizations
```http
GET /beta/v1/organizations HTTP/1.1
Accept: */*
```
#### Example Response for Listing Organizations
```json
[
  {
    "id": "text",
    "name": "text",
    "domain": "text",
    "role": "user",
    "kind": "direct",
    "is_primary": true,
    "denied_permissions": [
      "text"
    ]
  }
]
```
#### Example for Getting Organization Details
```http
GET /beta/v1/organizations/{org_id} HTTP/1.1
Accept: */*
```
#### Example Response for Getting Organization Details
```json
{
  "id": "text",
  "name": "text",
  "domain": "text",
  "created_at": "2026-07-27T21:09:26.461Z",
  "primary_address": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "zip": "text",
    "country": "text"
  }
}
```