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

# Workspaces & Teams

> Manage workspaces, invite team members, and control access with roles.

## Overview

Workspaces are the top-level organizational unit in Encrata. Each workspace has its own:

* API keys and usage quotas
* Team members with role-based access
* Monitors, workflows, and contact lists
* Billing and credit balance

***

## Workspace Management

### List Workspaces

```bash theme={"dark"}
GET /api/workspaces
```

Returns all workspaces the authenticated user belongs to.

***

### Create Workspace

```bash theme={"dark"}
POST /api/workspaces
```

| Field  | Type   | Required | Description                                         |
| ------ | ------ | -------- | --------------------------------------------------- |
| `name` | string | Yes      | Workspace display name                              |
| `slug` | string | No       | URL-friendly identifier (auto-generated if omitted) |

***

### Update Workspace

```bash theme={"dark"}
PUT /api/workspaces
```

| Field  | Type   | Description        |
| ------ | ------ | ------------------ |
| `name` | string | New workspace name |
| `slug` | string | New slug           |
| `logo` | string | Logo URL           |

***

### Delete Workspace

```bash theme={"dark"}
DELETE /api/workspaces
```

<Warning>
  This permanently deletes the workspace and all its data. Requires OTP verification.
</Warning>

***

### Switch Workspace

```bash theme={"dark"}
POST /api/workspaces/switch
```

| Field          | Type   | Required | Description                      |
| -------------- | ------ | -------- | -------------------------------- |
| `workspace_id` | string | Yes      | ID of the workspace to switch to |

***

## Team Members

### List Members

```bash theme={"dark"}
GET /api/workspaces/members
```

Returns all members of the current workspace with their roles.

**Response:**

```json theme={"dark"}
[
  {
    "id": "user_abc",
    "email": "alice@company.com",
    "name": "Alice",
    "role": "admin",
    "joined_at": "2026-01-15T10:00:00Z"
  }
]
```

***

### Invite Member

```bash theme={"dark"}
POST /api/workspaces/members
```

| Field   | Type   | Required | Description                            |
| ------- | ------ | -------- | -------------------------------------- |
| `email` | string | Yes      | Email address to invite                |
| `role`  | string | Yes      | Role: `admin`, `member`, or `readonly` |

The invited user receives an email with a link to accept the invitation.

***

### Update Member Role

```bash theme={"dark"}
PUT /api/workspaces/members
```

| Field     | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `user_id` | string | Yes      | User ID to update                          |
| `role`    | string | Yes      | New role: `admin`, `member`, or `readonly` |

***

### Remove Member

```bash theme={"dark"}
DELETE /api/workspaces/members
```

| Field     | Type   | Required | Description       |
| --------- | ------ | -------- | ----------------- |
| `user_id` | string | Yes      | User ID to remove |

***

### Leave Workspace

```bash theme={"dark"}
POST /api/workspaces/leave
```

Leave the current workspace. Requires OTP verification. Cannot leave if you're the only admin.

***

### Accept Invite

```bash theme={"dark"}
POST /api/workspaces/accept
```

Public endpoint accepts a workspace invitation using the token from the invite email.

| Field   | Type   | Required | Description                 |
| ------- | ------ | -------- | --------------------------- |
| `token` | string | Yes      | Invitation token from email |

***

## Roles

| Role       | Permissions                                                  |
| ---------- | ------------------------------------------------------------ |
| `admin`    | Full access manage members, billing, SSO, workspace settings |
| `member`   | Use all features lookups, workflows, monitors, API keys      |
| `readonly` | View-only access cannot create or modify resources           |

***

## SSO (Single Sign-On)

Enterprise workspaces can configure SSO for seamless team authentication.

### List SSO Connections

```bash theme={"dark"}
GET /api/sso/connections
```

### Create SSO Connection

```bash theme={"dark"}
POST /api/sso/connections
```

| Field      | Type   | Required | Description                     |
| ---------- | ------ | -------- | ------------------------------- |
| `provider` | string | Yes      | SSO provider: `saml`, `oidc`    |
| `name`     | string | Yes      | Display name                    |
| `domain`   | string | Yes      | Email domain to match           |
| `config`   | object | Yes      | Provider-specific configuration |

### Update SSO Connection

```bash theme={"dark"}
PUT /api/sso/connections
```

### Delete SSO Connection

```bash theme={"dark"}
DELETE /api/sso/connections
```

### Test SSO Connection

```bash theme={"dark"}
POST /api/sso/test
```

Validates the SSO configuration by attempting a test authentication flow.