Keycard (RFID)

Add and remove RFID keycards on Igloohome locks.

addKeycard

Opens a BLE registration window and waits for the user to tap a physical keycard on the lock's reader (45-second timeout). Once detected, registers the card on the server.

If server registration fails after the card is enrolled on lock hardware, the SDK automatically removes the card from the lock.

Signature

suspend fun addKeycard(
    deviceId: String,
    key: String,
    name: String,
    accessToken: String,
): AddKeycardResponse

func addKeycard(
    deviceId: String,
    key: String,
    name: String,
    accessToken token: String
) async throws -> CreateKeycardAccessResponse

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the lock.
`key`	`String`	Yes	Guest key with `ADD_CARD` permission.
`name`	`String`	Yes	User-assigned name for the keycard.
`accessToken`	`String`	Yes	Access token for server calls.

Return Type

data class AddKeycardResponse(
    val accessId: String,
    val name: String,
    val payload: String,
)

public struct CreateKeycardAccessResponse: Codable, Sendable {
    public let accessId: String
    public let name: String
    public let payload: String
}

Field	Description
`accessId`	Server-assigned access ID.
`name`	The name assigned to the keycard.
`payload`	Base64-encoded card UID.

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	Device disconnected during registration.
`TimeoutException`	703	No card tapped within 45 seconds.
`LockStorageFullException`	912	No storage for more keycards.
`ApiException`	varies	Server registration failed (card rolled back from lock).

Example

try {
    showPrompt("Tap your keycard on the lock reader...")
    val result = sdk.addKeycard(
        deviceId = "IGM4-XXXX",
        key = guestKey,
        name = "Office Badge",
        accessToken = accessToken,
    )
    showSuccess("Keycard registered: ${result.accessId}")
} catch (e: IglooHomeException.TimeoutException) {
    showError("No card detected — try again")
} catch (e: IglooHomeException.LockStorageFullException) {
    showError("Lock is full — delete a keycard first")
} catch (e: IglooHomeException) {
    showError("Failed: ${e.message}")
}

do {
    showPrompt(message: "Tap your keycard on the lock reader...")
    let result = try await sdk.addKeycard(
        deviceId: "IGM4-XXXX",
        key: guestKey,
        name: "Office Badge",
        accessToken: accessToken)
    showSuccess(message: "Keycard registered: \(result.accessId)")
} catch IgloohomeError.timeout {
    showError(message: "No card detected — try again")
} catch IgloohomeError.lockStorageFull {
    showError(message: "Lock is full — delete a keycard first")
} catch {
    showError(message: "Failed: \(error.localizedDescription)")
}

deleteKeycard

Removes a keycard from the lock and deletes the server record.

The SDK fetches the card UID from the server, removes it from lock hardware via BLE, then deletes the server record. If the card is already removed from the lock (BLE error 980), the SDK still deletes the server record.

Signature

suspend fun deleteKeycard(
    deviceId: String,
    key: String,
    accessId: String,
    accessToken: String,
)

func deleteKeycard(
    deviceId: String,
    key: String,
    accessId: String,
    accessType: AccessType = .rfid,
    accessToken token: String
) async throws

Parameters

Name	Type	Required	Description
`deviceId`	`String`	Yes	Bluetooth device name of the lock.
`key`	`String`	Yes	Guest key with `DELETE_CARD` permission.
`accessId`	`String`	Yes	Server-assigned access ID of the keycard to delete.
`accessToken`	`String`	Yes	Access token for server calls.

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	Device disconnected during deletion.
`TimeoutException`	703	BLE operation exceeded the timeout.
`ApiException`	varies	Server deletion failed.

Example

try {
    sdk.deleteKeycard(
        deviceId = "IGM4-XXXX",
        key = guestKey,
        accessId = "access-456",
        accessToken = accessToken,
    )
    showSuccess("Keycard removed")
} catch (e: IglooHomeException.ConnectionException) {
    showError("unexpected bluetooth connection issue")
} catch (e: IglooHomeException.TimeoutException) {
    showError("Timed out, try again")
} catch (e: IglooHomeException) {
    showError("Failed: ${e.message}")
}

do {
    try await sdk.deleteKeycard(
        deviceId: "IGM4-XXXX",
        key: guestKey,
        accessId: "access-456",
        accessToken: accessToken)
    showSuccess(message: "Keycard removed")
} catch {
    showError(message: "Failed: \(error.localizedDescription)")
}

Notes

Registration timeout is 45 seconds (hardcoded).
Server deletion retries up to 3 times with 1-second delays.
LockUidNotFoundException (980, Android) / IgloohomeError.lockUidNotFound (iOS) during BLE delete is non-fatal — server record is still removed.
Supported lock types: IWS, IGM3, IGM4, IGR, RG1, MP1F, ML5, RW1.