Projects, Keys and Environments

Resolve the organization, project and environment your key actually acts in, then use that answer to explain why a list came back empty, because the common cause is a live key reading a test project.

Prerequisites

npm install @codespar/sdk

The generic REST client used below (cs.api) landed in @codespar/sdk 0.12.0. Beyond a key, two things matter:

• GET /v1/whoami costs no scope. It is listed in the scope-exempt routes, so it answers for any key that authenticates at all.
• Everything else here does cost one. /v1/projects needs projects:read on the GET and projects:write on POST, PATCH and DELETE. The three settings routes need projects:settings. GET /v1/organizations/:id needs projects:read. A wildcard key, which is what every key created without an explicit scope list gets, passes before any of those are consulted.

1. Ask the server who the key is

This is the first call, and the only one in the recipe that spends no scope. It answers with organization (id and name), project (id and name), key (id, environment and scopes), and optionally user (email and name).

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });

const who = await cs.api.response("get", "/v1/whoami");
if (!who.ok) {
  throw new Error(`whoami refused with ${who.status}`);
}

const organization = who.data.organization;
const project = who.data.project;
const key = who.data.key;

console.log("org:", organization.id, organization.name);
console.log("project:", project.id, project.name);
console.log("environment:", key.environment);
console.log("scopes:", key.scopes);

curl -s https://api.codespar.dev/v1/whoami \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  | jq '{ org: .organization.id, project: .project.id, environment: .key.environment }'

cs.api.response(...) returns status, ok, data and response, and never throws on a refusal. Use it throughout this recipe, because the refusals are the point.

2. Read key.environment, not the prefix

The environment does not come from the key string. Authentication resolves the project the key is bound to and reads the environment column of that projects row. The prefix was stamped once, at creation, out of that same column, and is never compared to anything afterwards: the key lookup is by hash.

What holds the prefix to the truth is the creation side, not the request side. Key creation refuses with 400 env_mismatch when the body's environment differs from the project's.

3. Place the project inside the organization

GET /v1/projects returns every project in the organization, live and test together, the default first and then oldest to newest. It takes no query parameters and has no cursor. Match project.id from step 1 against a row: that row is what says whether the key acts in test or live, and whether the project is the default.

const list = await cs.api.response("get", "/v1/projects");
if (!list.ok) throw new Error(`projects refused with ${list.status}`);

const row = list.data.projects.find((p) => p.id === project.id);
if (!row) throw new Error("the key resolves to a project this organization does not list");

console.log(row.slug, row.environment, row.is_default);
console.log("other projects:", list.data.projects.map((p) => `${p.slug}:${p.environment}`));

curl -s https://api.codespar.dev/v1/projects \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  | jq '.projects[] | { id, slug, environment, is_default }'

4. Close the identity

Two optional reads. GET /v1/projects/{id} returns one row, and the organization is inside the query itself, so an id from another organization is a 404 rather than a 403. GET /v1/organizations/{id} answers only for your own organization id.

const one = await cs.api.response("get", "/v1/projects/{id}", {
  path: { id: project.id },
});
console.log(one.status, one.ok ? one.data.name : one.data.error.code);

const org = await cs.api.response("get", "/v1/organizations/{id}", {
  path: { id: organization.id },
});
console.log(org.status, org.ok ? org.data.name : org.data.error.code);

Pass any organization id other than your own and the answer is 404 not_found, including for an organization that exists. Nothing in this API lists or creates organizations.

5. Run the read that came back empty

Every data read filters on the org_id and project_id of the resolved context. GET /v1/sessions, GET /v1/wallets and GET /v1/consumers/funding-sources all do it the same way.

const sessions = await cs.api.response("get", "/v1/sessions");
console.log(sessions.status, sessions.data.sessions.length);

const wallets = await cs.api.response("get", "/v1/wallets");
console.log(wallets.status, wallets.data.wallets.length);

An empty array with a 200 is a correct answer, not an error. It means the project you resolved in steps 1 to 3 holds nothing of that kind. Three separate things produce it, and only one of them is a wrong key. See step 9.

6. Read the project settings

const settings = await cs.api.response("get", "/v1/projects/{id}/settings", {
  path: { id: project.id },
});
console.log(settings.status, settings.data.settings);

In a live project the answer today is an empty settings array, because all three declared settings (test_autotopup_enabled, standin_account, standin_pix_key) are registered for the test environment only. Empty here is normal and says nothing about the key.

GET /v1/projects/{id}/settings is the one route of the four under projects and settings with no role gate on it. The PATCH and the history read are administrative.

7. The header that does nothing

x-codespar-project is read only on the service-auth path. The csk_ key path never touches it. Sending it changes nothing, and the only symptom is exactly the empty read this recipe is investigating.

8. Separate the environments by creating a project

POST /v1/projects takes name (1 to 128, required), slug (lowercase letters, digits, underscore and hyphen, 1 to 64, required), environment (live or test, optional, default test) and settings (optional). It answers 201 with the project row.

const created = await cs.api.response("post", "/v1/projects", {
  body: {
    name: "Production",
    slug: "production",
    environment: "live",
  },
});

if (created.status === 400) {
  // invalid_body carries details.issues, or details.key for a rejected setting.
  // slug_conflict carries details.slug.
  throw new Error(`${created.data.error.code}: ${created.data.error.message}`);
}
if (!created.ok) throw new Error(`create refused with ${created.status}`);

console.log(created.data.id, created.data.environment, created.data.is_default);

curl -X POST https://api.codespar.dev/v1/projects \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "Production", "slug": "production", "environment": "live" }'

The write order matters when it fails. The handler validates the body, then validates each initial setting against the registry for the environment the project is about to be born in, then upserts the organization, then inserts the project, and only then writes the settings. A rejected setting refuses before the insert, so a bad settings object never leaves an orphan project behind.

A project created this way is always born with is_default false, and nothing in this API guarantees the organization has a default at all. At most one project carries true, held by a partial unique index. At least one is held by nothing.

9. Three causes of an empty read

Once the context is resolved, the empty list from step 5 has exactly three explanations, and two of them survive any key you swap in.

1. The key acts in another project. Steps 1 to 3 show it: project.id from whoami matches a row whose environment or slug is not the one you meant. The fix is a different key, issued from the dashboard for the project you want.
2. The project is new and empty. A project created by POST /v1/projects does not receive the shared sandbox seed. The seeding runs only inside the auto-created default project, and as a self-heal inside the meta-tools. A project created over the API starts with no connections, so the read is empty for a reason that has nothing to do with the key.
3. The rows carry a null project_id. In consumer_funding_sources, whatever the backfill could not attribute stays null and matches no project whatsoever. The route still returns unattributed_count, which counts exactly the rows it is hiding from everybody. No key reaches them.

10. Move the default, and write settings

PATCH /v1/projects/{id} accepts name, slug and is_default, and is_default only as the literal true. There is no environment field, in this route or anywhere else.

curl -X PATCH https://api.codespar.dev/v1/projects/prj_abc123def456gh \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "is_default": true }'

The handler clears the previous default and marks the new one in the same transaction, so no committed state ever shows two defaults. An empty patch body is invalid_body with the message "empty patch".

Settings are written in batches, and the response is the effective settings after the write, not only the keys you touched.

const written = await cs.api.response("patch", "/v1/projects/{id}/settings", {
  path: { id: project.id },
  body: { settings: { test_autotopup_enabled: true } },
});

if (written.status === 400) {
  // details.key names the offending setting when there is one.
  throw new Error(`${written.data.error.code}`);
}
console.log(written.data.settings);

A null value resets a key back to tracking the default. The whole batch is validated before any write happens, so one bad entry rejects everything and nothing changes.

11. Delete a project

DELETE /v1/projects/{id} answers 204 with no body. It refuses in a fixed order: 404 first if the project is not in your organization, then cannot_delete_default, then cannot_delete_last_project, then the consumer-record probe, then the delete itself.

const removed = await cs.api.response("delete", "/v1/projects/{id}", {
  path: { id: doomedProjectId },
});

if (removed.status === 409) {
  const code = removed.data.error.code;
  const blockedBy = removed.data.error.details?.blocked_by ?? [];
  for (const entry of blockedBy) {
    console.log(entry.table, entry.rows);
  }
  throw new Error(code);
}
if (removed.status !== 204) throw new Error(`delete refused with ${removed.status}`);

The probe is a single query over nine consumer tables with UNION ALL, so cannot_delete_with_consumer_records names every blocking table at once rather than one per attempt. There is one exception: when a row lands between the probe and the delete, the refusal carries a single table with rows of null, and blocked_by is empty when even that could not be identified.

Refusals, and which one a retry fixes

CLI

codespar login
codespar whoami
codespar whoami --json | jq -r '.project.id'

codespar login spends a GET /v1/whoami to prove the key works, and only then writes it to the config file with mode 0600. A key that fails is never persisted. codespar whoami runs the same single call and prints user, organization, project, key environment and scopes.

What this does not do

• There is no GET /v1/orgs. The served document has 16 paths under the org-scoped subtree for mandates, audit, agents, approvals and data subjects, but that exact path is not one of them. No listing, no creating, no updating an organization. The only readable organization resource is GET /v1/organizations/{id}, and only with your own id.
• No route takes a project parameter. Across all 276 operations in the served document there is no path, query or header parameter named for a project. x-codespar-project shows up only in the security-scheme prose and applies to a service credential.
• GET /v1/projects has no filter and no pagination, despite the query parameters and the paged response shape documented on the projects reference.
• slug_invalid and slug_reserved are not error codes. The reference page lists both. Neither string exists in the service. A reserved slug and a malformed slug both come back as invalid_body.
• slug_conflict is not a 409. The reference page says 409; the handler answers 400. The error reference gets this one right, and the two pages contradict each other.
• environment is missing from the Project object table on the reference page, although it is a required column on the real row and the axis of this entire recipe.
• No key creation, rotation or revocation over the API. POST /v1/api-keys is service auth and is not in the served document, so there is no SDK method and no CLI command for it either. The same is true of the project members routes, which the Projects concept page shows as if they were callable.
• No CLI command for projects, orgs or organizations. The exclusion is deliberate and the reason is recorded in the CLI surface list: dashboard surface. Only codespar login and codespar whoami exist here.
• No hand-written SDK methods. There is no cs.projects.list() and no cs.whoami(). Everything goes through cs.api, the REST client generated from the document. ApiClient.operations() lists every reachable method and path if you want to check.
• No way to change a project's environment. PATCH does not accept the field, and a database trigger blocks the update. The path is a second project.
• The scope numbers on Authentication are stale. That page counts 14 route entries against roughly 198 routes. The map today carries 289 route entries and covers every reachable route, with the unmapped count held at zero.
• The role gate and the unmapped-route gate are both off by default in the code. What a given deployment has set for them is an environment question, not a code question.

Next steps