Projects

CodeSpar uses a 2-level tenancy model: Organization -> Project. Every resource -- sessions, API keys, triggers, connections, events -- belongs to exactly one project, and every project belongs to exactly one organization.

Projects are the unit of environment isolation. A typical setup has one organization per company and multiple projects inside it (for example dev, staging, prod), each with its own API keys, connected accounts, and audit log.

Why projects

Before projects, every resource was scoped to the organization. That forced teams to either share credentials across environments or spin up separate orgs just to keep dev from touching prod. Projects fix that without splitting billing, team membership, or settings:

• Environment isolation -- dev, staging, and prod live side by side under one org with independent API keys and OAuth connections.
• Per-project audit -- tool calls, sessions, and events are filtered by project in the dashboard.
• Per-project limits -- quota and rate-limit counters can be scoped per project (see Billing).
• Same team, same billing -- members, plan, and invoice live at the organization level and apply across all projects.

The default project

Every organization has a default project, auto-created at signup. If you never touch projects, everything you create lands there and the HTTP API works exactly as before -- no header required.

Find your default project's ID in the dashboard under Dashboard -> Projects, or via the API:

curl "https://api.codespar.dev/v1/projects?is_default=true" \
  -H "Authorization: Bearer csk_live_..."

Project IDs and slugs

Passing a project on requests

All /v1 endpoints accept the x-codespar-project header:

curl -X POST https://api.codespar.dev/v1/sessions \
  -H "Authorization: Bearer csk_live_..." \
  -H "x-codespar-project: prj_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{"servers": ["stripe"]}'

Resolution order:

1. If the API key is project-scoped (pinned to one project), the key's project always wins and x-codespar-project is ignored.
2. Otherwise, if x-codespar-project is present, that project is used.
3. Otherwise, the request falls back to the organization's default project.

Project-scoped API keys

An API key can optionally be pinned to a single project via its project_id column. When a request authenticates with a project-scoped key:

• The key's project is resolved automatically -- you do not need to send x-codespar-project.
• If the key holder does send x-codespar-project and it does not match the key's project, the header is ignored (the key wins).

This is the recommended pattern for CI/CD, production workloads, and anything else that should be locked to one environment. Create project-scoped keys from Dashboard -> Projects -> [project] -> API Keys.

Unpinned keys (no project_id) behave like org-level keys: they can operate on any project via x-codespar-project, and fall back to the default project when the header is omitted.

Dashboard routing

Per-project surfaces in the dashboard live under /dashboard/projects/[projectId]/...:

A Project Switcher in the sidebar swaps the active project across all of these. Project CRUD lives at /dashboard/projects.

Common workflows

Promote a non-default project to default

is_default is promoted atomically via PATCH /v1/projects/:id with {"is_default": true}. The previous default is demoted in the same transaction. You cannot un-set is_default directly -- to change the default, promote a different project instead.

Delete a project

curl -X DELETE https://api.codespar.dev/v1/projects/prj_... \
  -H "Authorization: Bearer csk_live_..."

Deletion fails with:

• cannot_delete_default -- promote a different project to default first.
• cannot_delete_last_project -- every org must have at least one project.

Next steps