Data

Your Shell app reads and writes records in your workspace's collections — tables in your database — as the signed-in user. Every workspace already has a database, so there's nothing to set up first. You can see and edit the same data in Data → Data Vault in the Client Portal.

Query records

The starter kit's queryCollection helper sends the request with the user's token:

import { queryCollection } from "./lib/queryVault";

const page = await queryCollection<Customer>("customers", {
  filter: { status: "active" },
  sort: ["-created_at", "name"],
  limit: 25,
  offset: 0,
});
// page.items, page.total, page.has_more

Create, update and delete

Call the API with the user's token. The workspace ID and API address come from the Shell:

const base = `${window.__GF_CONTROLPLANE_URL__}/v1/workspaces/${window.__GF_WORKSPACE_ID__}/vault/collections/customers`;
const headers = {
  Authorization: `Bearer ${await window.__GF_GET_ACCESS_TOKEN__()}`,
  "Content-Type": "application/json",
};

await fetch(base, { method: "POST", headers, body: JSON.stringify({ name: "Acme" }) });       // create
await fetch(`${base}/${id}`, { method: "PUT", headers, body: JSON.stringify({ name: "Acme Ltd" }) }); // update
await fetch(`${base}/${id}`, { method: "DELETE", headers });                                  // delete

Every request and field is in the Data Vault API.

Who can read and write

Each collection grants read, write and delete separately to each of your site's roles. A new collection is open only to admins, so grant access before your users can see it:

• Client Portal: Data → Data Vault → the collection's Access.
• API: PUT …/vault/collections/{name}/acl with grants such as { "role": "user", "action": "write" }.

Your app's users can't create or delete collections. Create them in the Client Portal or with your team's credentials. A 403 from a Shell app almost always means the user's role has no grant on that collection.

Grants apply to a whole collection, not to individual records. If users must only see or change their own records, don't grant their roles that collection; have your app's backend (a Coderunner) read and write it with an M2M client instead. Match records by the token's sub claim (the user's ID); see Know who the user is. See Who can use a collection.

Next steps

• Data Vault — create collections and browse data.
• Files — store uploads alongside your records.