Workspaces

How workspaces and organizations are structured in Locus.

Overview

Locus uses a two-level hierarchy:

• Organizations — Top-level containers that group workspaces and team members

• Workspaces — Project-level containers where tasks, sprints, and documents live

---

Organizations

An organization represents your team or company. Each organization has members with specific roles:

Role	Permissions
Owner	Full control, manage members, delete organization
Admin	Manage workspaces, tasks, sprints, and API keys
Member	Create and work on tasks, view workspaces
Viewer	Read-only access to workspaces and tasks

---

Workspaces

A workspace maps to a single project or repository. It contains:

• Tasks — Units of work with status, priority, and acceptance criteria

• Sprints — Time-boxed iterations grouping tasks

• Documents — Knowledge base for the project (PRDs, tech specs, etc.)

• API Keys — Scoped credentials for CLI access

Creating a Workspace

1. Log in to app.locusai.dev

2. Select your organization

3. Click Create Workspace

4. Name it after your project

---

API Keys

API keys are scoped to a workspace. They authenticate the CLI and Telegram bot.

Your workspace is automatically resolved from the API key. You don't need to manually configure a workspace ID.

Generating a Key

1. Open your workspace in the dashboard

2. Go to Settings → API Keys

3. Click Create API Key

4. Copy and store the key securely

Using the Key

locus config setup --api-key "your-key"

Or set it directly:

locus config set apiKey "your-key"

Never commit API keys to your repository. The .locus/settings.json file is automatically added to .gitignore by locus init.