PIN Management

Create and delete custom PINs on Igloohome locks.

createPin

Creates a custom PIN on the lock via Bluetooth and registers it on the server. The SDK writes the PIN to lock hardware first, then registers on the server. If server registration fails, the SDK automatically deletes the PIN from the lock.

Signature

suspend fun createPin(
    deviceId: String,
    key: String,
    pin: String,
    pinType: PinType,
    name: String,
    startTimeInSeconds: Long? = null,
    endTimeInSeconds: Long? = null,
    accessToken: String,
): CreatePinResponse

func createPin(
    deviceId: String,
    key: String,
    name: String,
    pin: String,
    pinType: PinType,
    startDate: Date?,
    endDate: Date?,
    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 `CREATE_PIN` permission.
`pin`	`String`	Yes	PIN code (numeric, 1–12 digits).
`pinType`	`PinType`	Yes	PIN type: `ONETIME`, `PERMANENT`, or `DURATION`.
`name`	`String`	Yes	User-assigned name for the PIN.
`startTimeInSeconds`	`Long?`	Duration only	Start time in epoch seconds. Required for `DURATION` type.
`endTimeInSeconds`	`Long?`	Duration only	End time in epoch seconds. Required for `DURATION` type.
`accessToken`	`String`	Yes	Access token for server calls.

Supporting Types

enum class PinType {
    ONETIME,
    PERMANENT,
    DURATION,
}

public enum PinType: String, Sendable {
    case otp = "otp"
    case permanent = "permanent"
    case duration = "duration"
}

Return Type

data class CreatePinResponse(
    val accessId: String,
    val name: String,
    val pin: String,
    val pinType: String,
    val startDateTime: String?,
    val endDateTime: String?,
)

Error Codes

Exception	Code	Description
`BluetoothException`	708	Bluetooth is off or unavailable.
`ConnectionException`	12	Device disconnected during PIN creation.
`TimeoutException`	703	BLE operation exceeded the timeout.
`DuplicatePinException`	880	PIN already exists on the lock.
`LockStorageFullException`	912	No storage for more PINs on the lock.
`ApiException`	varies	Server registration failed (PIN rolled back from lock).

Example

try {
    val result = sdk.createPin(
        deviceId = "IGM4-XXXX",
        key = guestKey,
        pin = "123456",
        pinType = PinType.PERMANENT,
        name = "Front Door PIN",
        accessToken = accessToken,
    )
    println("PIN created: ${result.accessId}")
} catch (e: IglooHomeException.DuplicatePinException) {
    showError("This PIN already exists on the lock")
} catch (e: IglooHomeException.LockStorageFullException) {
    showError("Lock is full — delete a PIN first")
} catch (e: IglooHomeException) {
    showError("Failed: ${e.message}")
}

do {
    try await sdk.createPin(
        deviceId: "IGM4-XXXX",
        key: guestKey,
        name: "Front Door PIN",
        pin: "123456",
        pinType: .permanent,
        startDate: nil,
        endDate: nil,
        accessToken: accessToken)
    showSuccess(message: "PIN created")
} catch IgloohomeError.duplicatePin {
    showError(message: "This PIN already exists on the lock")
} catch IgloohomeError.lockStorageFull {
    showError(message: "Lock is full — delete a PIN first")
} catch {
    showError(message: "Failed: \(error.localizedDescription)")
}

deletePin

Deletes a PIN from the lock and removes the server record.

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

Signature

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

func deletePin(
    deviceId: String,
    key: String,
    accessId: String,
    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_PIN` permission.
`accessId`	`String`	Yes	Server-assigned access ID of the PIN 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.deletePin(
        deviceId = "IGM4-XXXX",
        key = guestKey,
        accessId = "access-123",
        accessToken = accessToken,
    )
    showSuccess("PIN deleted")
} 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.deletePin(
        deviceId: "IGM4-XXXX",
        key: guestKey,
        accessId: "access-123",
        accessToken: accessToken)
    showSuccess(message: "PIN deleted")
} catch {
    showError(message: "Failed: \(error.localizedDescription)")
}

Notes

Server deletion retries up to 3 times with 1-second delays on failure.
PinNotFoundException (890, Android) / IgloohomeError.pinNotFound (iOS) during BLE delete is treated as non-fatal — the SDK continues to delete the server record.