Link UI

Link UI is a hosted page where your end users sign in to their device manufacturer and choose which devices to share with you. You send them a URL; they come back to your app with their devices linked.

Build the URL

Each Link UI app has an appId. Create one in the dashboard under Link UI, which also shows the app’s URL.

https://auth.amps.ai/{appId}?externalUserRef=user_8841

Parameter
`externalUserRef`	Your ID for this end user. Up to 100 characters: letters, digits, and `.` `_` `+` `-` `@`. Other characters make Link UI generate a random ID instead.
`sandbox`	`true` to link sandbox devices. Omit for live.

Live links only work once your account is enabled for live. An out-of-range value in any parameter makes Link UI ignore all of them, including sandbox, so validate them before you build the URL. Customization covers the parameters that shape the flow.

What the end user does

Pick a device type

Pick a manufacturer

Agree to share their devices

On Link UI, on the manufacturer’s own page, or by entering details printed on the device. Completes MFA if asked. Link UI fills in the device’s time zone from the browser, and the user can correct it.

Select the devices to link

Return to your app

Clicking Return to sends them to your app’s redirect URL.

The redirect carries no parameters. Listen for the device.connected webhook, or list the user’s devices.

Find a user’s devices

The externalUserRef you passed is the user’s userId in the API. Filter any device list by it.

curl "https://api.amps.ai/battery?userId=user_8841" \
  -H "x-api-key: $AMPS_API_KEY"

If you omit externalUserRef, Link UI generates a random ID that you have no way to read back. Always pass your own.

Sandbox

Create the app with the dashboard switched to sandbox. Its URL includes sandbox=true. For manufacturers that use a username and password or an API key, any value is accepted and the account has two devices. Manufacturers that sign in on their own page approve automatically. To test failures, enter a value starting with error, or the MFA code 000000.

https://auth.amps.ai/{appId}?sandbox=true&externalUserRef=test_user_1

Devices linked this way are visible to your sk_test_ key.

Reconnect

When a manufacturer stops accepting a user’s credentials, you get a device.disconnected webhook with a reconnectionUrl. Add externalUserRef with the user’s ID to that URL, then send the user there. They sign in again, their devices keep the same IDs, and you get device.reconnected.

{reconnectionUrl}&externalUserRef=user_8841

Without it, Link UI can’t match the devices to the user. After reconnecting, Link UI sends the user to your app’s reconnect redirect URL. When a user disconnects in your app, revoke their consent. Omit deviceIds to revoke every device the user linked.

curl -X DELETE https://api.amps.ai/users/user_8841/consent \
  -H "x-api-key: $AMPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deviceIds": ["device_abc123"] }'

{
  "success": true,
  "data": {
    "userId": "user_8841",
    "revokedDeviceCount": 1,
    "revokedDeviceIds": ["device_abc123"]
  }
}

When no other link uses the device, and the manufacturer supports it, Amps also hands the device back to its owner at the manufacturer. If that step fails, the request fails and nothing is revoked. Requests for a revoked device return 403 CONSENT_REVOKED. A userId with no matching devices returns 404 NOT_FOUND. The user can grant access again by linking the device through Link UI with the same externalUserRef.

Next steps

Customization

Your name, logo, manufacturers, and flow options.

Webhooks

Get notified when devices connect or disconnect.

Pull

Read the state of a linked device.

Get started

API Reference

Guides

Cookbooks

Build the URL

What the end user does

Find a user’s devices

Sandbox

Reconnect

Next steps

Customization

Webhooks

Pull

​Build the URL

​What the end user does

​Find a user’s devices

​Sandbox

​Reconnect

​Revoke consent

​Next steps

Customization

Webhooks

Pull

Build the URL

What the end user does

Find a user’s devices

Sandbox

Reconnect

Revoke consent

Next steps