Quickstart

This page walks you through the shortest path to building on Hane. You prepare an API key, call the public API with the SDK, apply a type definition with hanectl, and check the record you created in the console.

Before you begin

• Node.js 22.13 or later
• An organization and a project. An organization administrator (owner or admin role) sets these up
• The URL of the Hane gateway. On this page it is stored in the HANE_API environment variable

Tip

To try things locally, run pnpm dev and pnpm dev:seed from Local development. This creates a sample organization acme, a project fleet, and an API key in one go. The gateway URL is http://localhost:8787.

Steps

1. Prepare a service account and an API key

   An app calls Hane as a service account, a caller that is not a person. A service account is bound to one project and environment, and its scopes are fixed when you create it. Using an administrator’s access token (print it with hanectl token), create one like this:

   import { createHaneClient, unwrap } from "@hane/sdk";
   
   const admin = createHaneClient({ baseUrl: process.env.HANE_API!, token: () => process.env.ADMIN_TOKEN ?? null });
   
   const sa = await unwrap(
     admin.POST("/v1/platform/service-accounts", {
       body: {
         name: "quickstart",
         project: "fleet",
         environment: "dev",
         scopes: ["data:schemas.read", "data:records.read", "data:records.write", "definitions:read", "definitions:apply", "definitions:release"],
       },
     }),
   );
   const key = await unwrap(admin.POST("/v1/platform/service-accounts/{id}/keys", { params: { path: { id: sa.sa_id } } }));
   console.log(key.secret); // hane_dev_... returned only in this response

   You can also issue and revoke API keys in the console under Access → Service accounts and API keys. Keep the value in a file such as .env and never commit it to Git.

2. Add the SDK Preview

   Add the TypeScript SDK @hane/sdk to your app’s dependencies. The SDK is a thin client on top of openapi-fetch and runs in both browsers and Node.js. The package is not yet published to a public registry, so ask your provider how to obtain it. To call Hane from other languages, use the OpenAPI document in the API reference.

3. Call the public API

   Create a client with the API key as token and read the types in the active release.

   import { createHaneClient, unwrap } from "@hane/sdk";
   
   const hane = createHaneClient({
     baseUrl: process.env.HANE_API!,
     token: () => process.env.HANE_API_KEY ?? null,
   });
   
   const { types } = await unwrap(hane.GET("/v1/data/types"));
   console.log(types.map((t) => t.type)); // empty until you add definitions

4. Log in with hanectl

   hanectl is the CLI for definitions and projects. When you log in with an API key, its organization, project, and environment become the current context.

   hanectl login --api-key "$HANE_API_KEY" --org acme --project fleet --env dev --server "$HANE_API"

5. Write a definition and apply it

   Write a type in definitions/schemas/vehicle.yaml, and list what goes into the ReleaseBundle in bundle.yaml in the same directory.

   definitions/schemas/vehicle.yaml

   apiVersion: data/v1alpha1
   kind: Schema
   metadata:
     name: vehicle
   spec:
     type: Vehicle
     key: registration_no
     display: registration_no
     fields:
       registration_no: { type: string, title: Registration number }
       model: { type: string, title: Model }
       inspection_expiry: { type: string, format: date, title: Inspection expiry }
     required: [registration_no]

   definitions/bundle.yaml

   apiVersion: release/v1alpha1
   kind: Bundle
   metadata:
     name: quickstart
   spec:
     resources:
       - schemas/

   hanectl validate -f definitions   # check shape and references locally
   hanectl diff -f definitions       # see what apply would change
   hanectl apply -f definitions      # save as drafts (not in effect yet)

6. Create and activate a ReleaseBundle

   Drafts take effect when you bundle them into a ReleaseBundle and activate it.

   hanectl release create -f definitions/bundle.yaml --activate

7. Create a record and view it in the console

   Create one record with the SDK. Each value is passed as { value }.

   const record = await unwrap(
     hane.POST("/v1/data/records", {
       body: {
         type: "Vehicle",
         values: {
           registration_no: { value: "TEST 300 A 10-01" },
           model: { value: "Van" },
           inspection_expiry: { value: "2027-03-31" },
         },
       },
     }),
   );
   console.log(record.id, record.values.inspection_expiry?.state);

   Log in to the console. Check the active ReleaseBundle under Definitions and releases, and the record and its value states on the data pages.

Caution

To keep this page short, one service account also holds the scopes that change definitions (definitions:apply and definitions:release). In a real app, use separate service accounts for running the app and for the CI that applies definitions. Activations in prod are done by a person with their own login.

Next steps

App structureHow to split screens, the BFF, the SDK, and definitions

AuthenticationAPI keys, access tokens, token exchange, scopes

Writing manifestsDefinition kinds, file layout, CEL

Reference app tutorialRun and read the vehicle lease app