Get Started with Aqara Locks

Overview

Seam provides a universal API to connect and control many brands of smart locks. This guide provides a rapid introduction to connecting and controlling your Aqara lock using the Seam API. To learn more about other smart lock brands supported by Seam, head over to our integration page.

1 — Install Seam SDK

Seam provides client libraries for many languages, such as JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and OpenAPI spec.

JavaScript / TypeScript (npm, GitHub)
Python (pip, GitHub)
Ruby Gem (rubygem, GitHub)
PHP (packagist, GitHub)
C# (nuget, GitHub)
Java (GitHub)

npm i seam

pip install seam
# For some development environments, use pip3 in this command instead of pip.

bundle add seam

composer require seamapi/seam

Once installed, sign up for Seam to get your API key, and export it as an environment variable:

$ export SEAM_API_KEY=seam_test2ZTo_0mEYQW2TvNDCxG5Atpj85Ffw

This guide uses a Sandbox Workspace. Only virtual devices can be connected. If you need to connect a real Aqara lock, use a non-sandbox workspace and API key.

2 — Link Aqara Account with Seam

To control your Aqara lock via the Seam API, you must first authorize your Seam workspace against your Aqara account. To do so, Seam provides Connect Webviews: pre-built UX flows that walk you through authorizing your application to control your Aqara lock.

Request a Connect Webview

import { Seam } from 'seam'

const seam = new Seam()

const connectWebview = await seam.connectWebviews.create({
  accepted_providers: ['aqara'],
})

console.log(connectWebview.login_successful) // false

// Send the webview URL to your user
console.log(connectWebview.url)

from seam import Seam

seam = Seam()

webview = seam.connect_webviews.create(
    accepted_providers=["aqara"]
)

assert webview.login_successful is False

# Send the webview URL to your user
print(webview.url)

require "seam"

seam = Seam.new()

webview = seam.connect_webviews.create(
  accepted_providers: ["aqara"]
)

puts webview.login_successful # false

# Send the webview URL to your user
puts webview.url

<?php
use Seam\SeamClient;

$seam = new SeamClient("YOUR_API_KEY");

$webview = $seam->connect_webviews->create(
  accepted_providers: ["aqara"]
);

echo $webview->login_successful; // false

// Send the webview URL to your user
echo $webview->url;

using Seam.Client;

var seam = new SeamClient(apiToken: "YOUR_API_KEY");

var webview = seam.ConnectWebviews.Create(
  acceptedProviders: new List<string> { "aqara" }
);

Console.WriteLine(webview.LoginSuccessful); // false

// Send the webview URL to your user
Console.WriteLine(webview.Url);

import co.seam.Seam;
import co.seam.api.types.ConnectWebview;

Seam seam = Seam.builder().apiKey("YOUR_API_KEY").build();

ConnectWebview webview = seam.connectWebviews().create(
  ConnectWebviewsCreateRequest.builder()
    .acceptedProviders(List.of("aqara"))
    .build()
);

System.out.println(webview.getLoginSuccessful()); // false

// Send the webview URL to your user
System.out.println(webview.getUrl());

curl -X 'POST' \
  'https://connect.getseam.com/connect_webviews/create' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "accepted_providers": ["aqara"]
  }'

Authorize Your Workspace

Navigate to the URL returned by the Webview object. Since you are using a sandbox workspace, complete the login flow by entering the Aqara sandbox test account credentials below:

email: jane@example.com
password: 1234
region: United States

Confirm the Connect Webview was successful by querying its status:

const updatedWebview = await seam.connectWebviews.get(
  connectWebview.connect_webview_id,
)

console.log(updatedWebview.login_successful) // true

updated_webview = seam.connect_webviews.get(
    connect_webview_id=webview.connect_webview_id
)

assert updated_webview.login_successful # true

updated_webview = seam.connect_webviews.get(
  connect_webview_id: webview.connect_webview_id
)

puts updated_webview.login_successful # true

<?php
$updated_webview = $seam->connect_webviews->get(
  connect_webview_id: $webview->connect_webview_id
);

echo $updated_webview->login_successful; // true

var updatedWebview = seam.ConnectWebviews.Get(
  connectWebviewId: webview.ConnectWebviewId
);

Console.WriteLine(updatedWebview.LoginSuccessful); // true

ConnectWebview updatedWebview = seam.connectWebviews().get(
  ConnectWebviewsGetRequest.builder()
    .connectWebviewId(webview.getConnectWebviewId())
    .build()
);

System.out.println(updatedWebview.getLoginSuccessful()); // true

curl -X 'POST' \
  'https://connect.getseam.com/connect_webviews/get' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"connect_webview_id\": \"${CONNECT_WEBVIEW_ID}\"
  }"

3 — Retrieve Aqara Lock Devices

After an Aqara account is linked with Seam, you can retrieve devices for this Aqara account. The Seam API exposes most of the device’s properties such as battery level or door lock status.

const allLocks = await seam.locks.list()

const someLock = allLocks[0]

console.log(someLock.properties.online) // true
console.log(someLock.properties.locked) // true

console.log(someLock)
/*
{
  device_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
  device_type: 'aqara_lock',
  capabilities_supported: ['lock', 'access_code'],
  properties: {
    locked: true,
    online: true,
    manufacturer: 'aqara',
    aqara_metadata: {
      device_name: 'Aqara Smart Lock U200',
      model: 'aqara.matter.4447_10242'
    },
    name: 'Aqara Smart Lock U200',
    battery: {
      level: 0.65,
      status: 'good'
    }
  },
  location: null
}
*/

all_locks = seam.locks.list()

some_lock = all_locks[0]

assert some_lock.properties["online"] is True
assert some_lock.properties["locked"] is True

print(some_lock)

# Device(
#     device_id='aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
#     device_type='aqara_lock',
#     location=None,
#     properties={
#         'locked': True,
#         'online': True,
#         'manufacturer': 'aqara',
#         'aqara_metadata': {
#             'device_name': 'Aqara Smart Lock U200',
#             'model': 'aqara.matter.4447_10242'
#         },
#         'name': 'Aqara Smart Lock U200',
#         'battery': {
#             'level': 0.65,
#             'status': 'good'
#         }
#     },
#     capabilities_supported=['lock', 'access_code']
# )

some_lock = seam.locks.list.first

puts some_lock.properties.online # true
puts some_lock.properties.locked # true

puts some_lock.inspect

# <Seam::Device:0x00438
#   device_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
#   device_type="aqara_lock"
#   properties={
#     "locked"=>true,
#     "online"=>true,
#     "manufacturer"=>"aqara",
#     "aqara_metadata"=>{
#       "device_name"=>"Aqara Smart Lock U200",
#       "model"=>"aqara.matter.4447_10242"
#     },
#     "name"=>"Aqara Smart Lock U200",
#     "battery"=>{"level"=>0.65, "status"=>"good"}
#   }
# >

<?php
$locks = $seam->locks->list();

$some_lock = $locks[0];

echo $some_lock->properties->online; // true
echo $some_lock->properties->locked; // true

echo json_encode($some_lock, JSON_PRETTY_PRINT);

// {
//   "device_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
//   "device_type": "aqara_lock",
//   "properties": {
//     "locked": true,
//     "online": true,
//     "manufacturer": "aqara",
//     "aqara_metadata": {
//       "device_name": "Aqara Smart Lock U200",
//       "model": "aqara.matter.4447_10242"
//     },
//     "name": "Aqara Smart Lock U200",
//     "battery": {
//       "level": 0.65,
//       "status": "good"
//     }
//   }
// }

var locks = seam.Locks.List();

var someLock = locks[0];

Console.WriteLine(someLock.Properties.Online); // true
Console.WriteLine(someLock.Properties.Locked); // true

Console.WriteLine(someLock);

// {
//   "device_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
//   "device_type": "aqara_lock",
//   "properties": {
//     "locked": true,
//     "online": true,
//     "manufacturer": "aqara",
//     "aqara_metadata": {
//       "device_name": "Aqara Smart Lock U200",
//       "model": "aqara.matter.4447_10242"
//     },
//     "name": "Aqara Smart Lock U200",
//     "battery": {
//       "level": 0.65,
//       "status": "good"
//     }
//   }
// }

var locks = seam.locks().list();

var someLock = locks.get(0);

System.out.println(someLock.getProperties().getOnline()); // true
System.out.println(someLock.getProperties().getLocked()); // true

System.out.println(someLock);

// {
//   "device_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
//   "device_type": "aqara_lock",
//   "properties": {
//     "locked": true,
//     "online": true,
//     "manufacturer": "aqara",
//     "aqara_metadata": {
//       "device_name": "Aqara Smart Lock U200",
//       "model": "aqara.matter.4447_10242"
//     },
//     "name": "Aqara Smart Lock U200",
//     "battery": {
//       "level": 0.65,
//       "status": "good"
//     }
//   }
// }

curl -X 'POST' \
  'https://connect.getseam.com/locks/list' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{}'

4 — Lock and Unlock a Door

Next, you can perform the basic action of locking and unlocking the door.

Lock a door

await seam.locks.lockDoor({ device_id: someLock.device_id })

seam.locks.lock_door(device_id=some_lock.device_id)

seam.locks.lock_door(device_id: some_lock.device_id)

<?php
$seam->locks->lock_door(device_id: $some_lock->device_id);

seam.Locks.LockDoor(deviceId: someLock.DeviceId);

seam.locks().lockDoor(
  LocksLockDoorRequest.builder()
    .deviceId(someLock.getDeviceId())
    .build()
);

curl -X 'POST' \
  'https://connect.getseam.com/locks/lock_door' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"device_id\": \"${DEVICE_ID}\"
  }"

Unlock a door

await seam.locks.unlockDoor({ device_id: someLock.device_id })

seam.locks.unlock_door(device_id=some_lock.device_id)

seam.locks.unlock_door(device_id: some_lock.device_id)

<?php
$seam->locks->unlock_door(device_id: $some_lock->device_id);

seam.Locks.UnlockDoor(deviceId: someLock.DeviceId);

seam.locks().unlockDoor(
  LocksUnlockDoorRequest.builder()
    .deviceId(someLock.getDeviceId())
    .build()
);

curl -X 'POST' \
  'https://connect.getseam.com/locks/unlock_door' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"device_id\": \"${DEVICE_ID}\"
  }"

5 — Set Access Codes

Seam enables you to set access codes on Aqara locks with a keypad. You can create ongoing codes that remain active until removed, or timebound codes that are only active during a specified time window.

Create an ongoing access code

const accessCode = await seam.accessCodes.create({
  device_id: someLock.device_id,
  name: 'My Access Code',
  code: '1234',
})

console.log(accessCode)
/*
{
  access_code_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  device_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
  name: 'My Access Code',
  code: '1234',
  type: 'ongoing',
  status: 'setting'
}
*/

access_code = seam.access_codes.create(
    device_id=some_lock.device_id,
    name="My Access Code",
    code="1234"
)

print(access_code)

# AccessCode(
#     access_code_id='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
#     device_id='aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
#     name='My Access Code',
#     code='1234',
#     type='ongoing',
#     status='setting'
# )

access_code = seam.access_codes.create(
  device_id: some_lock.device_id,
  name: "My Access Code",
  code: "1234"
)

puts access_code.inspect

# <Seam::AccessCode:0x00438
#   access_code_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
#   device_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
#   name="My Access Code"
#   code="1234"
#   type="ongoing"
#   status="setting"
# >

<?php
$access_code = $seam->access_codes->create(
  device_id: $some_lock->device_id,
  name: "My Access Code",
  code: "1234"
);

echo json_encode($access_code, JSON_PRETTY_PRINT);

// {
//   "access_code_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
//   "device_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
//   "name": "My Access Code",
//   "code": "1234",
//   "type": "ongoing",
//   "status": "setting"
// }

var accessCode = seam.AccessCodes.Create(
  deviceId: someLock.DeviceId,
  name: "My Access Code",
  code: "1234"
);

Console.WriteLine(accessCode);

// {
//   "access_code_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
//   "device_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
//   "name": "My Access Code",
//   "code": "1234",
//   "type": "ongoing",
//   "status": "setting"
// }

var accessCode = seam.accessCodes().create(
  AccessCodesCreateRequest.builder()
    .deviceId(someLock.getDeviceId())
    .name("My Access Code")
    .code("1234")
    .build()
);

System.out.println(accessCode);

// {
//   "access_code_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
//   "device_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
//   "name": "My Access Code",
//   "code": "1234",
//   "type": "ongoing",
//   "status": "setting"
// }

curl -X 'POST' \
  'https://connect.getseam.com/access_codes/create' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"device_id\": \"${DEVICE_ID}\",
    \"name\": \"My Access Code\",
    \"code\": \"1234\"
  }"

Create a timebound access code

const timeboundCode = await seam.accessCodes.create({
  device_id: someLock.device_id,
  name: 'Guest Access',
  starts_at: '2025-01-01T16:00:00Z',
  ends_at: '2025-01-08T12:00:00Z',
})

console.log(timeboundCode)
/*
{
  access_code_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  device_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
  name: 'Guest Access',
  type: 'time_bound',
  starts_at: '2025-01-01T16:00:00.000Z',
  ends_at: '2025-01-08T12:00:00.000Z',
  status: 'unset'
}
*/

timebound_code = seam.access_codes.create(
    device_id=some_lock.device_id,
    name="Guest Access",
    starts_at="2025-01-01T16:00:00Z",
    ends_at="2025-01-08T12:00:00Z"
)

print(timebound_code)

# AccessCode(
#     access_code_id='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
#     device_id='aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
#     name='Guest Access',
#     type='time_bound',
#     starts_at='2025-01-01T16:00:00.000Z',
#     ends_at='2025-01-08T12:00:00.000Z',
#     status='unset'
# )

timebound_code = seam.access_codes.create(
  device_id: some_lock.device_id,
  name: "Guest Access",
  starts_at: "2025-01-01T16:00:00Z",
  ends_at: "2025-01-08T12:00:00Z"
)

puts timebound_code.inspect

# <Seam::AccessCode:0x00438
#   access_code_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
#   device_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
#   name="Guest Access"
#   type="time_bound"
#   starts_at="2025-01-01T16:00:00.000Z"
#   ends_at="2025-01-08T12:00:00.000Z"
#   status="unset"
# >

<?php
$timebound_code = $seam->access_codes->create(
  device_id: $some_lock->device_id,
  name: "Guest Access",
  starts_at: "2025-01-01T16:00:00Z",
  ends_at: "2025-01-08T12:00:00Z"
);

echo json_encode($timebound_code, JSON_PRETTY_PRINT);

var timeboundCode = seam.AccessCodes.Create(
  deviceId: someLock.DeviceId,
  name: "Guest Access",
  startsAt: "2025-01-01T16:00:00Z",
  endsAt: "2025-01-08T12:00:00Z"
);

Console.WriteLine(timeboundCode);

var timeboundCode = seam.accessCodes().create(
  AccessCodesCreateRequest.builder()
    .deviceId(someLock.getDeviceId())
    .name("Guest Access")
    .startsAt("2025-01-01T16:00:00Z")
    .endsAt("2025-01-08T12:00:00Z")
    .build()
);

System.out.println(timeboundCode);

curl -X 'POST' \
  'https://connect.getseam.com/access_codes/create' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"device_id\": \"${DEVICE_ID}\",
    \"name\": \"Guest Access\",
    \"starts_at\": \"2025-01-01T16:00:00Z\",
    \"ends_at\": \"2025-01-08T12:00:00Z\"
  }"

Next Steps

Now that you’ve connected and controlled your Aqara lock with the Seam API, explore the following resources:

Access Codes — Learn more about managing access codes.
Webhooks — Set up event-driven notifications for lock activity.
Connect Webviews — Build custom authorization flows for your users.
Core Concepts — Understand workspaces, devices, and connected accounts.

Overview

Smart Locks

Access Control Systems

Intercoms

Thermostats

Noise Sensors

Cameras

Other Devices

Get Started with Aqara Locks

Overview

1 — Install Seam SDK

2 — Link Aqara Account with Seam

Request a Connect Webview

Authorize Your Workspace

3 — Retrieve Aqara Lock Devices

4 — Lock and Unlock a Door

Lock a door

Unlock a door

5 — Set Access Codes

Create an ongoing access code

Create a timebound access code

Next Steps

​Overview

​1 — Install Seam SDK

​2 — Link Aqara Account with Seam

​Request a Connect Webview

​Authorize Your Workspace

​3 — Retrieve Aqara Lock Devices

​4 — Lock and Unlock a Door

​Lock a door

​Unlock a door

​5 — Set Access Codes

​Create an ongoing access code

​Create a timebound access code

​Next Steps

Overview

1 — Install Seam SDK

2 — Link Aqara Account with Seam

Request a Connect Webview

Authorize Your Workspace

3 — Retrieve Aqara Lock Devices

4 — Lock and Unlock a Door

Lock a door

Unlock a door

5 — Set Access Codes

Create an ongoing access code

Create a timebound access code

Next Steps