Skip to main content
GET
/
workspaces
List Workspaces
curl --request GET \
  --url https://app.tokencraft.dev/api/v1/workspaces \
  --header 'Authorization: Bearer <token>'

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

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. 
Authorization: Bearer tkc_your_token_here

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer tokenYes

​
Parameters

None

​
Response

​
Success Response

Status: 200 OK 
{
  "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

FieldTypeDescription
workspacesarrayArray of workspace objects
totalnumberTotal number of workspaces

​
Workspace Object

FieldTypeDescription
idstringUnique workspace identifier
namestringWorkspace name
descriptionstring|nullOptional description
user_idstringOwner’s user ID
user_role"owner"|"admin"|"editor"|"viewer"Caller role in this workspace
is_ownerbooleantrue when caller role is owner
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

​
Examples

curl -H "Authorization: Bearer tkc_your_token_here" \
  https://app.tokencraft.dev/api/v1/workspaces

​
Error Responses

​
401 Unauthorized

{
  "error": "Invalid API token"
}

​
500 Internal Server Error

{
  "error": "Internal server error"
}

​
Use Cases

​
1. Initial App Load

Fetch all workspaces when user opens your application: 
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: 
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: 
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 for details.

​
Next Steps

Get Workspace

Get details of a specific workspace

Get Tokensets

List tokensets in a workspace