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. Store and match records by the sub claim of the token it verified (the user's ID, with Groundfloor and External sign-in), not by external_user_id; see Use sub as the user's ID. See Who can use a collection.

Next steps

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