Documentation

CoAP POST /iam/pairing/password-open

DESCRIPTION

This endpoint pairs the current user with the target device that hosts the endpoint.

Prior to invocation, the current user must have been password authenticated on the connection using the device’s Password open pairing password (vs. a per-user assigned pairing password). Hence, this endpoint is used for Password open pairing.

To password authenticate a connection, the client application uses the SDK function nabto_client_connection_password_authenticate(), specifing an empty string as username and the password for Password open pairing.

For password invite pairing use the password-invite endpoint.

DECLARATION

POST /iam/pairing/password-open

REQUEST

The client specifies the desired username to use on the target device. The username must be unique on the target device, and can only use the character set:

  • Lower case letters [a-z].
  • Numbers [0-9].
  • The underscore character _.
  • The dash character -.
  • The period character ..

The fingerprint set on the resulting user can optionally be named with the body field FingerprintName.

The request is CBOR encoded.

{
  "Username": "john_doe",
  "FingerprintName": "my phone"
}

By naming the fingerprint using FingerprintName, you ensure easy identification of user fingerprints, especially if multiple devices are paired later (e.g. “my tablet” or “my laptop”).

RESPONSE

CoAP status codes:

  • 201: Pairing completed successfully.
  • 201: Already paired.
  • 400: Bad request (likely invalid username).
  • 401: Missing password authentication.
  • 403: Blocked by IAM configuration.
  • 404: Pairing mode disabled.
  • 409: Username/fingerprint exists.

IAM PARAMETERS

A user must have access to the following IAM Action to use this endpoint:

  • IAM:PairingPasswordOpen

No special attributes are provided.