One portal for the entire Abra integration.

Amplify Auth adapter

If your browser application already uses Amplify Auth, pass its fetchAuthSession function into the included adapter.

import { fetchAuthSession } from "aws-amplify/auth";
import {
  createAbraClient,
  createAmplifyTokenProvider,
} from "@abra-connect/sdk";

const client = createAbraClient({
  endpoint: import.meta.env.VITE_APPSYNC_URL,
  tokenProvider: createAmplifyTokenProvider(fetchAuthSession, {
    tokenType: "access",
  }),
});

Any other authentication library

const client = createAbraClient({
  endpoint: "https://your-api.appsync-api.eu-west-1.amazonaws.com/graphql",
  tokenProvider: async () => {
    const session = await yourAuthLibrary.getSession();
    return session.accessToken;
  },
});

The provider runs before every request. That lets your authentication library refresh the session without exposing refresh logic to the SDK.

const client = createAbraClient({
  endpoint,
  tokenProvider,
  allowDeviceControl: true,
});

// The valve operation is a device mutation.
// Show a confirmation and verify that it is safe before opening.
await client.devices.setValveOpen("water-valve-device-id", true);

// A leak alarm is a home-level alarm record, not a device command.
const alarms = await client.alarms.list("home-id");
const waterAlarm = alarms.find(
  (alarm) =>
    alarm.__typename === "WaterAlarm"
    && (alarm.state === "ALARM" || alarm.state === "SNOOZED"),
);

if (waterAlarm) {
  // Resolving the alarm does not open the valve.
  await client.alarms.resolve(waterAlarm.id);
}

await client.devices.setOn("light-device-id", true);
await client.devices.setBrightness("light-device-id", 70);
await client.devices.setOpenPercent("blind-device-id", 40);

1. Check capability: show only commands returned for that device.
2. Explain the effect: name the home, room, device, and new state.
3. Confirm: require an intentional user action for safety-sensitive changes.
4. Wait for result: display command acceptance or the typed error.
5. Refresh state: do not assume the physical device changed immediately.

Operation names and inputs in this guide are checked against the bundled Abra GraphQL schema.

Custom GraphQL

const data = await client.graphql(
  `query MyHomeIds {
    homes {
      id
      homeInfo { nickname }
    }
  }`,
  {},
  { operation: "Load home names" },
);

What the customer does

Supported API-to-Homey mapping

Login and SDK connection

import Homey from "homey";
import { createAbraClient } from "@abra-connect/sdk";

// abraSession is created by the Homey pairing and login flow.
const client = createAbraClient({
  endpoint: Homey.env.ABRA_APPSYNC_URL,
  tokenProvider: async () => abraSession.getCurrentToken(),
  allowDeviceControl: true,
});

const homes = await client.homes.list();

What “Experimental” means

• ✓
  API operations are usableAuthenticated reads, reporting age, alarm records, device controls, and alarm resolution are already available through the SDK.
• E
  Homey adapter is experimentalThe pairing interface, session persistence, device drivers, capability mappings, and Flow cards are the experimental integration layer.
• ↻
  State refresh starts with pollingThe current SDK covers GraphQL queries and mutations. Poll only within the provisioned API limits until AppSync subscription support is added.
• !
  Backend permission remains authoritativeHomey must handle expired sessions and rejected controls, while Abra verifies access to every requested home and device.

This experimental functionality describes the supported path for pilot and customer-developed Homey integrations. It does not imply that an installable Homey package is already included with the JavaScript SDK. See the Homey Apps SDK documentation for Homey application and driver structure.

• ✓
  API permissionUse the endpoint and integration rights provisioned for your organization.
• ✓
  Public app clientNever embed a Cognito client secret in browser or mobile code.
• ✓
  Short-lived tokensRefresh sessions through an approved host authentication flow.
• ✓
  Secure storageChoose storage appropriate to the host and never log token values.
• ✓
  Resolver authorizationCheck user, home, and device ownership on every query and mutation.
• ✓
  Control confirmationRequire clear user intent for locks, valves, alarms, heat, and charging.
• ✓
  HTTPS and CSPServe production apps over HTTPS with a restrictive Content Security Policy.
• ✓
  Rate limitsKeep polling and retries within the documented API limits.