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

Environments — live vs test

Every project has an environment field, set at creation and immutable afterward. This is independent of the API key prefix (csk_live_ vs csk_test_), but the two must match — a csk_test_ key cannot operate on a live project, and vice-versa.

Common gotcha

The most frequent first-day support ticket: a csk_live_ key was minted, but it points at the org's default project which happens to be test. Every request returns 401 unauthorized and it looks like the key is broken. Fix: either issue a csk_test_ key or create a live project and pin the key there. Check project.environment in the dashboard's project list.

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.

Grant per-project access without making someone an org admin

By default, every org member inherits the same role across all projects. To narrow or widen that — give a contractor admin access to one staging project without exposing production, or give a member admin rights on a specific project — use project-level role overrides:

curl -X POST https://api.codespar.dev/v1/projects/prj_.../members \
  -H "Authorization: Bearer csk_live_..." \
  -d '{"user_id": "user_contractor456", "role": "admin"}'

Absence of an override = inherits the org role. Endpoints documented in Projects API → Project members. Dashboard UI is on the roadmap; for now, this is API-only.

Next steps