Connectors: the descriptor and the four routes
A connector in ALYT is described to clients by an integration descriptor, and that descriptor drives what the console and phone show for the catalogue card, connect flow, discovery, disconnect consequence, and guide link. A developer works with the descriptor on GET /integrations/catalogue, the connector-specific routes it serves, and the rules around built-in connectors, pairing, rediscovery, and state refresh. The platform keeps working in the house when the cloud is down, but a household sees less than staff; and a DEV key acts in a sandbox while a LIVE key only works for its own connector.
What an integration descriptor contains
Section titled “What an integration descriptor contains”A connector is described once per kind by an integration descriptor. The clients render from that descriptor and do not name connectors directly in client code.
| Field | Meaning |
|---|---|
kind, name, icon, promise | identity and the one sentence shown on the card |
connectivity | local, cloud, or cloud-then-local; shown as a badge where the disconnect consequence is shown |
brings | the kind of things it can add |
connect.method | one of discover, form, signIn, oauth, pair; for form, signIn, and pair, this also defines the fields the client renders |
discovery | present when the connector can look for things on the network |
disconnect.consequence | the sentence shown before Disconnect, with counts filled in |
author, version, source, visibility | who made it and whether it ships with the platform or is registered through the developer portal, for one tenant or every tenant |
verification | proven with the date a probe reached a real device, or declared when it has not been probed here |
availability | added by the server when serving the catalogue: available today, or coming when only the description exists |
A coming card is shown but cannot be connected. If the client meets a method it does not know, it still shows the card and the message to connect from the console.
The catalogue and the connected list
Section titled “The catalogue and the connected list”GET /integrations/catalogue returns every listed descriptor with availability. GET /integrations returns what is connected, including things and lastSeen, and never config.
The connected list is what the household uses to manage connectors. The clients also use the catalogue to render connect screens and the disconnect consequence. A descriptor can also carry docsUrl, which the card and connect screen link to as “Read the guide”.
Connect, challenge, and settings
Section titled “Connect, challenge, and settings”POST /integrations connects from what the person typed, or answers a challenge. It can return:
connectedchallengerejected
A challenge means the provider wants one more step, such as a code emailed by Ring. The client re-posts with the token and the answer, rendered from the same field descriptor.
PATCH /integrations/:id is the settings route. It reuses the same fields as the connect screen for rename or new credentials, validates them through the connector, and then replaces the stored values. It can also return connected, challenge, or rejected.
Rights matter here: connecting, discovering, and disconnecting are configure, which means the client OWNER, or tenant staff for a tenant-wide integration. Controlling what is connected is for everyone.
The four connector routes
Section titled “The four connector routes”Every connector speaks four routes behind its own runtime path.
| Route | When | Answers |
|---|---|---|
POST /{kind}/connect | for form, signIn, pair, oauth | connected, challenge, or rejected after a real call to the provider |
POST /{kind}/discover | when the descriptor declares discovery | current discovery results, and sometimes a new config if the connector learns something new |
POST /{kind}/state | on refresh | current state per endpoint, and failures per item |
POST /{kind}/control | on a command | performs one write and returns the state read back |
The connector receives config on later calls after a successful connect. For discovery, a built-in connector can sync what it found through POST /integrations/:id/endpoints, while a submitted connector returns each endpoint in full and tenant-service lands them itself.
Discovery, pairing, and supported devices
Section titled “Discovery, pairing, and supported devices”POST /integrations/:id/discover is also the route used again when a connected integration can look again. For pairing connectors, it returns joinOpenSeconds, pending, found, endpoints, and note, and the clients keep polling while the add sheet is open.
Pairing is driven by the pairing descriptor field, which carries joinSeconds, an intro, vendors, optional actions, and a source date. The guide shown to the person is rendered from the API, not from client code, so a guide edit reaches the console and the phone without a release.
POST /integrations/:id/actions takes { action, input }. The server refuses an action the descriptor does not declare. A declared action is forwarded to the connector’s POST /{kind}/action with the stored config, and the result is done or rejected.
GET /integrations/:id/supported?vendor= returns the supported-device list for one brand in the guide. The list comes from the connector’s POST /{kind}/supported with the guide’s matchVendors, and the response is in a list envelope.
Built-in connectors and rediscovery
Section titled “Built-in connectors and rediscovery”A descriptor can carry builtIn: { reason }. A built-in kind exists exactly once per home, and the platform creates it before GET /integrations?clientId= answers if the connector reports the hardware is present. A home without the hardware never sees it. The catalogue card shows “built in” and no Connect, and the connected card’s Disconnect reads “Forget all its devices”.
Rediscovery upserts an endpoint by provider id. If the endpoint already exists, discovery refreshes its kind, address, and capabilities, and leaves its name and room alone. If a provider knows a room name, it sends roomName with the endpoint and it is placed by it; if it does not, the endpoint arrives unassigned.
A connector may also push state for a device it hears directly, by calling POST /integrations/:id/endpoints/:externalId/state with { tenantId, state }. The endpoint must already exist under that integration and tenant, and the state is merged the same way refresh merges it.
What the house sees
Section titled “What the house sees”The house keeps working when the cloud is down. The clients still show what they can reach locally, but a household sees less than staff. That distinction matters for connectors that are local, cloud, or cloud-then-local, and for the guide and card content that tells the person what to expect.
DELETE /integrations/:id disconnects and answers how many things were removed and which rooms they were in.
Developer portal pages and reviews
Section titled “Developer portal pages and reviews”Every listed descriptor has a developer portal page at https://developers.alyt.com/connectors/<kind>, generated from the descriptor and the connector guide, and served as JSON beside the page. A proven connector must have a guide, and verification is re-audited on schedule.
A developer publishes a definition version, and a house runs one version of it. That keeps a later submission from silently changing what a home uses. GET /integrations/catalogue is narrowed by visibility, so a PRIVATE definition is visible only to its own tenant.
Key scope
Section titled “Key scope”A DEV key acts in a sandbox. A LIVE key only works for its own connector. That difference matters whenever you test the connect, discover, state, or control routes.