Skip to main content

Connecting Your App

An App Registration represents an application that can access data in your SyncHive hive. During registration, you define which shapes the application can use and where the application is hosted.

Registering an App​

To create an App Registration:

  1. Open Connect and select Apps.
  2. Select Register App.
  3. Enter a name for the application.
  4. Select one or more shapes.
  5. Leave the status as Enabled.
  6. Save the registration.

Assigning Shapes​

Every app registration must be assigned one or more shapes.

Shapes determine the data structures available to the application and define the information that can be exchanged through SyncHive.

An application can be assigned multiple shapes, and the same shape can be used by multiple applications.

Connection Details​

Once the app registration has been created, SyncHive generates a ready-to-use prompt snippet with a publishable key for connecting your application.

Option 1: Copy the generated prompt snippet​

This is the recommended approach. The generated snippet already includes the publishable key, assigned shapes, and instructions for connecting to SyncHive. Paste the snippet into your AI coding tool and describe the application you want to build.

Option 2: Copy the publishable key only​

Use the key directly if you prefer to write your own prompt or configure the connection manually.

Application URLs​

App Registrations can include one or more application URLs.

These URLs identify where the application is hosted and are used by SyncHive when validating application access.

When creating a new application, it is common not to know the final application URL yet. In this case, you can leave the App URL(s) field empty and update it later.

Many application development platforms generate temporary or preview URLs while an application is being built. These URLs may change during development and are often different from the URL ultimately used when the application connects to SyncHive.

Once the application has been deployed and is ready to connect, update the App Registration with the application's current URL.

If an application cannot connect successfully, one of the first things to verify is that the URL being used by the application has been added to the App Registration.

Advanced Configuration​

The section above focuses on creating an app registration and connecting your first application.

The following information is aimed at users building or configuring applications directly. It explains how applications connect to SyncHive, access data, and manage authentication.

If you are using an AI coding tool to generate your application, you can usually skip this section. The generated prompt snippet already references the relevant SyncHive documentation, allowing the AI tool to access the technical implementation details it needs while generating the application.

Building Your App​

SyncHive Apps are built using the official SyncHive JavaScript SDK, which handles sign-in and secure access automatically.

View the SDK on GitHub: SyncHive JavaScript SDK.

Most apps install it via npm:

npm install @synchive/synchive-js

Once installed, your app can connect to SyncHive. In the snippet below, replace the placeholder value for publishableKey with the publishable key from the app's connection details.

import { SyncHiveClient } from "@synchive/synchive-js";

const synchive = new SyncHiveClient({
  publishableKey: "sh_publishable_...",
});

// Initialize the client first.
try {
  await synchive.init();
} catch (error) {
  // Surface sign-in callback errors to the user.
  console.error("Auth failed:", error);
}

// Listen for auth lifecycle events.
synchive.onAuthStateChange(({ user }, event) => {
  // Fires immediately on mount, then whenever auth state changes.
  if (event === "authenticated") {
    // User is signed in. Show logged-in UI.
    // setUser(user);
  }

  if (event === "unauthenticated") {
    // User is signed out. Show logged-out UI.
    // setUser(null);
  }
});

// Call these from your UI event handlers:
// await synchive.signInRedirect();
// await synchive.signOutRedirect();

Quick flow:

  1. Create SyncHiveClient with your app's publishableKey.
  2. Call await synchive.init() once on app startup.
  3. React to onAuthStateChange events to render signed-in vs signed-out UI.
  4. Use signInRedirect() and signOutRedirect() from your UI event handlers.

Requesting Data from SyncHive​

After signing in, you can access SyncHive data using simple helper methods.

List Records​

Use list() to fetch records from a shape:

const products = await synchive.list("Product", {
  top: 20,
});

Get a Specific Record​

Use get() to retrieve a single record by its hiveId:

const product = await synchive.get("Product", "D6BFA0AB71A1");

Create a Record​

Use create() to create a new record in a shape:

const createdProduct = await synchive.create("Product", {
  name: "Two-Slice Toaster",
  sku: "TOASTER-2S-BLK",
});

create() returns the full created shape record.

Update a Record​

Use update() to update an existing record by hiveId. For update requests, the root hiveId is required in the payload. You can pass either a partial shape or a full shape:

const updatedProduct = await synchive.update("Product", "D6BFA0AB71A1", {
  hiveId: "D6BFA0AB71A1",
  status: "discontinued",
});

You can soft delete a record using update() by setting isDeleted to true.

note

isDeleted must be enabled on the shape before you can use soft deletes.

update() returns the full updated shape record unless it has been soft deleted, in which case it returns nothing.

You can view soft-deleted records in SyncHive Explore by clicking Filter, then Show Deleted, and then Apply Filters.

Filtering and Paging​

You can pass query options such as:

  • top controls how many records are returned, with a maximum of 500 per request.
  • skip controls how many records are skipped before returning results.
  • filter lets you request only records that match specific conditions.
  • orderby sorts records by one or more fields. Use asc or desc.

Additional details:

  • If top is greater than 500, SyncHive uses 500 instead.
  • For orderby, use a comma-separated list, such as createdOn desc,name asc.

Example:

const salesOrders = await synchive.list("SalesOrder", {
  filter:
    "transactionNumber eq 'TOASTER-1001' and salesOrderItem/any(i: i/name eq '4-Slice Toaster')",
  orderby: "createdOn desc,transactionNumber asc",
  skip: 0,
  top: 25,
});

Supported filters​

SyncHive supports only this subset of the OData filter syntax:

  • Comparison operators: eq, ne, gt, lt, ge, le
  • Logical operators: and, or, not
  • Collection operators: any, all
  • One text function: contains(field,'value')

Examples of supported filters:

status eq 'Active'
status ne 'Inactive'
hiveId eq 'D6BFA0AB71A1'
amount gt 100 and amount lt 500
total ge 1000 or discount le 25
not (status eq 'Archived')
salesOrderItem/any(i: i/name eq '4-Slice Toaster')
salesOrderItem/all(i: i/quantity ge 1)
contains(customerName,'Acme')

hiveId filters support only the eq operator.

Unsupported filters​

SyncHive does not currently support:

  • Other OData functions such as startswith(), endswith(), length(), or tolower()
  • Lambda expressions beyond any and all
  • Full OData query features such as expand or advanced nested function combinations

Examples of unsupported filters:

startswith(customerName,'A')
endswith(customerName,'Inc')
hiveId ne 'D6BFA0AB71A1'
length(customerName) gt 10
tolower(customerName) eq 'acme'
salesOrderItem/filter(i: i/qty gt 1)
contains(tolower(customerName),'acme')
expand=salesOrderItem

If a filter uses syntax not listed in Supported filters, treat it as unsupported.

Troubleshooting​

App URLs​

If your sign-in does not work, the most common cause is an App URL mismatch.

When this happens, you will see:

Access Denied
The app has not been registered in SyncHive to use the following URL...

This means the app URL you entered in SyncHive does not exactly match the URL your app is using during sign-in.

Common issues​

A missing or extra slash​

Entered in SyncHive:

https://my-app.com/sign-in

App is using:

https://my-app.com/sign-in/

http vs https​

Entered in SyncHive:

https://my-app.com/sign-in

App is using:

http://my-app.com/sign-in

Different web address​

Entered in SyncHive:

https://portal.my-app.com/sign-in

App is using:

https://my-app.com/sign-in

Different path or capitalization​

Entered in SyncHive:

https://my-app.com/Sign-In/

App is using:

https://my-app.com/sign-in/

How to fix​

  1. Copy the URL provided to you on the Access Denied page.
  2. Open Apps in SyncHive and select your app.
  3. Paste the URL you copied on the Access Denied page into one of the App URL(s) fields.
  4. Save your changes.
  5. Try signing in again.