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

# List Workspaces

> Retrieve all workspaces for the authenticated user

# List Workspaces

Retrieves all workspaces visible to the authenticated token user.

For TEAM-owned workspaces, this includes owned + shared workspaces where the caller is a member.
For non-TEAM-owned workspaces, visibility remains owner-only.

## Endpoint

```
GET /workspaces
```

## Authentication

Requires a valid API token in the Authorization header.

```bash theme={null}
Authorization: Bearer tkc_your_token_here
```

## Request

### Headers

| Header          | Value        | Required |
| --------------- | ------------ | -------- |
| `Authorization` | Bearer token | Yes      |

### Parameters

None

## Response

### Success Response

**Status:** `200 OK`

```json theme={null}
{
  "workspaces": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Design System",
      "description": "Main product design system",
      "user_id": "user-123",
      "user_role": "owner",
      "is_owner": true,
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Marketing Site",
      "description": "Marketing website tokens",
      "user_id": "owner-456",
      "user_role": "editor",
      "is_owner": false,
      "created_at": "2025-01-10T08:30:00Z",
      "updated_at": "2025-01-14T16:45:00Z"
    }
  ],
  "total": 2
}
```

### Response Fields

| Field        | Type   | Description                |
| ------------ | ------ | -------------------------- |
| `workspaces` | array  | Array of workspace objects |
| `total`      | number | Total number of workspaces |

### Workspace Object

| Field         | Type                                   | Description                      |
| ------------- | -------------------------------------- | -------------------------------- |
| `id`          | string                                 | Unique workspace identifier      |
| `name`        | string                                 | Workspace name                   |
| `description` | string\|null                           | Optional description             |
| `user_id`     | string                                 | Owner's user ID                  |
| `user_role`   | `"owner"\|"admin"\|"editor"\|"viewer"` | Caller role in this workspace    |
| `is_owner`    | boolean                                | `true` when caller role is owner |
| `created_at`  | string                                 | ISO 8601 timestamp               |
| `updated_at`  | string                                 | ISO 8601 timestamp               |

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer tkc_your_token_here" \
    https://app.tokencraft.dev/api/v1/workspaces
  ```

  ```javascript JavaScript theme={null}
  const token = 'tkc_your_token_here';

  const response = await fetch('https://app.tokencraft.dev/api/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  const data = await response.json();
  console.log(data.workspaces);
  ```

  ```python Python theme={null}
  import requests

  token = 'tkc_your_token_here'

  response = requests.get(
      'https://app.tokencraft.dev/api/v1/workspaces',
      headers={'Authorization': f'Bearer {token}'}
  )

  data = response.json()
  print(data['workspaces'])
  ```

  ```go Go theme={null}
  package main

  import (
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      token := "tkc_your_token_here"
      
      client := &http.Client{}
      req, _ := http.NewRequest("GET", "https://app.tokencraft.dev/api/v1/workspaces", nil)
      req.Header.Set("Authorization", "Bearer "+token)
      
      resp, _ := client.Do(req)
      defer resp.Body.Close()
      
      var data map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&data)
      fmt.Println(data["workspaces"])
  }
  ```
</CodeGroup>

## Error Responses

### 401 Unauthorized

```json theme={null}
{
  "error": "Invalid API token"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": "Internal server error"
}
```

## Use Cases

### 1. Initial App Load

Fetch all workspaces when user opens your application:

```javascript theme={null}
async function loadWorkspaces() {
  const data = await fetch(url, { headers }).then(r => r.json());
  
  // Display in UI
  renderWorkspaceSelector(data.workspaces);
  
  // Store in state
  store.dispatch(setWorkspaces(data.workspaces));
}
```

### 2. Workspace Selector

Build a dropdown menu:

```jsx theme={null}
function WorkspaceSelector({ workspaces }) {
  return (
    <select>
      {workspaces.map(ws => (
        <option key={ws.id} value={ws.id}>
          {ws.name}
        </option>
      ))}
    </select>
  );
}
```

### 3. Check for Workspaces

Verify user has created workspaces:

```javascript theme={null}
const { workspaces, total } = await getWorkspaces();

if (total === 0) {
  showOnboarding('Create your first workspace!');
}
```

## Rate Limiting

This endpoint counts toward your rate limit of 100 requests per minute.

See [Rate Limits](/api-reference/rate-limits) for details.

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Workspace" icon="folder" href="/api-reference/workspaces/get">
    Get details of a specific workspace
  </Card>

  <Card title="Get Tokensets" icon="layer-group" href="/api-reference/workspaces/tokensets">
    List tokensets in a workspace
  </Card>
</CardGroup>