Core concepts

Start with the workspace, then define the data and the operations that run inside it. The console uses product-facing names; APIs and the CLI sometimes use the underlying GSB names.

The platform at a glance

In the product	In APIs and code	How it fits
Account	Authenticated user	Your identity, with access granted to particular workspaces.
Workspace	Tenant; tenantCode	The isolation boundary in which backend operations run.
Workspace edition	Core, Corporate, or SaaS	The backend capabilities installed in that workspace.
Entity definition	entityDef; entDefName in queries	The schema for a type of business record, such as Customer.
Record	Entity	One customer, invoice, or other instance of a definition.
Field	Property	A value or reference declared by the definition.
Backend logic	Function or workflow	Code or a process operating within an authorized workspace.

For example, your account can have access to an Operations workspace. Inside that workspace, a Customer definition describes the fields, customer records hold the values, and a workflow can coordinate an approval involving those records. Changing the selected workspace changes the backend context; it does not create another account.

Tenant

Workspace = tenant when referring to a Pikbase workspace. Workspace is the product name; tenant is the backend term for its isolation boundary. You do not provision a separate tenant after creating a workspace.

Use the workspace code, not its display name, wherever an API takes tenantCode or a CLI command takes --tenant. Keep these technical identifiers unchanged in code. For example, gsb init --tenant your-workspace-code selects the workspace context for the CLI.

Every authorized operation runs in tenant context. Do not infer access from a URL or a client-supplied code; the server must authorize it. Where an operation permits an omitted tenantCode, it uses the tenant from the verified token. See authentication and workspace access for the exact session and authorization boundaries.

Account, edition, and SaaS subtenant

An account is your identity, not a workspace. Signing up is free; workspace signup and purchase are paid paths. A workspace edition determines the installed backend capabilities, not a different kind of identity. Compare Core, Corporate, and SaaS editions.

In the SaaS edition, subtenant refers to a customer context managed by your SaaS application. Distinguish that customer context from the platform workspace running the application. A SaaS customer's subscription is not the subscription used to purchase the platform workspace.

Entity

An entity is a business record with a unique identifier, properties, optional relationships, and metadata — a customer, project, ticket, or invoice.

Read one with getById, a page of them with query, and duplicate one with getCopy.

const customer = await entityService.getById(
  "Customer",
  "customer-123",
  token,
  tenantCode,
);

if (!customer) {
  throw new Error("Customer not found");
}

Entity definition

An entity definition is the schema contract for a class of entities: property names and types, constraints, references, indexes, and display metadata. It is itself a record, so it is readable at runtime.

Read one with getEntityDef, list them with queryEntityDefs, and evolve them with createEntityDef and updateEntityDef.

const definition = await entityDefService.getEntityDef(
  { entityDef: { name: "Customer" } },
  token,
  tenantCode,
);

Property

Properties hold scalar values, structured values, or references. Evolve them through the definition operations rather than relying on undocumented shapes.

Use getCommonPropertyDefs to discover the available data types, then addProperty, updateProperty, and removeProperty.

await entityDefService.addProperty(
  {
    entityDef: { name: "Customer" },
    property: { name: "loyaltyTier", title: "Loyalty tier" },
  },
  token,
  tenantCode,
);

Relationship

Mapped-item operations maintain relationships between entities. Use them when the definition models a relation rather than embedding copied data.

Attach with saveMappedItems, detach with removeMappedItems, and read across a relation with queryMapped or include() on a query.

Workflow

Workflows coordinate longer-running business processes. Start one with startWorkflow when the caller should not wait; use runWorkflow only when the caller needs the outcome inline. A waiting human task is advanced by its assignee with submitWorkflowTask, or programmatically with iterateTask; administrators step a run one activity at a time with iterateOnce.

See the workflows guide for the full lifecycle.

Function

A serverless function is tenant-resident backend code. Execute a saved function with runWfFunction. Use testWfFunction to execute a supplied definition without saving that definition, but isolate the test because its operations can still write data, upload files, or invoke external services. See serverless functions.