This guide contains all the relevant information about the device binding feature, including the key concepts and necessary endpoints to implement the feature in your banking solution.
The device binding API provides endpoints for customers to register their devices for use with your solution and create public/private key pairs for authenticating multi-factor authentication (MFA) challenges.
Device binding is a required component of Strong Customer Authentication (SCA) and the device signing authentication method, in which the customer verifies that their request originates from their registered device.
Once a customer binds their device, they will receive authentication challenges that they must confirm using the device (e.g., logging in, changing their data, authorizing transactions). Customers can create multiple restricted or unrestricted key pairs.
Your customers can authorize actions using either a restricted or an unrestricted key pair depending on the type of action:
- Unrestricted key pair does not require user authentication.
- Restricted key pair requires user authentication via biometrics (e.g., Touch ID or Face ID). For example, you need to combine the
privateKeyUsageflag
with theuserPresence
ortouchIDAny
iniOS
orsetUserAuthenticationParameters()
inAndroid
.
See the Strong customer authentication guide for more information about device signing and the full list of use cases requiring restricted and unrestricted keys.
You must ensure that your device binding implementation meets the following security requirements:
- A customer may only have a maximum of five registered devices.
- Each device must meet the minimum operating system requirements: Android 8.0 or above, or iOS 12 or above.
- Each device must support hardware-backed and strong security services via separate secure execution environments, e.g., Secure Enclave in iOS or TEE in Android OS.
- Your frontend must enforce a minimum device access security policy, such as requiring the user to set a device passcode.
- You must store personalized security credentials and cryptographic keys in a separate secure environment.
The following diagram gives an overview of the integration flow for device binding:
- The customer initiates the device binding process and enters the device's information through your application.
- Your application generates a private/public key pair in
ecdsa-p256
format. - Send the public key (in raw hex-encoded format) and the customer's information to Solaris using POST Create device.
- The Solaris API verifies the customer's information, stores the public key in the database, and then returns a change request object that your customer must confirm.
- Solaris sends a six-digit one-time password (OTP) via SMS to the customer's registered mobile number.
- The customer receives the OTP via SMS and enters it through your app.
- The customer signs the OTP with the private key and creates a signature on your application.
- Send the customer's signature to Solaris for verification by calling PUT Verify the signature.
- Solaris verifies the signature challenge and, if valid, registers the device and binds it to the customer.
- Create additional keys if required.
In this step, your customer must enter the required information about their device on your frontend. The device must meet the minimum security requirements. Afterward, your application must create a private/public key pair in ecdsa-p256
format for the customer.
This endpoint creates a device and attaches it to a specific customer. You must include the following attributes in the request body:
person_id
: The uniqueperson_id
for the customer on Solaris' system.key_type
: The supported format of the key type. Currently, onlyecdsa-p256
is supported, and you must send it to Solaris in raw hex-encoded format.challenge_type
: The type of challenge to be used to verify the device. The default value issms
.name
: The customer's device name. It must be the device's actual model—for example, Samsung Galaxy S10, Samsung Galaxy Note, etc.key_purpose
: Possible values arerestricted
orunrestricted
.key
: The hex-encoded public key generated for the device to be registered.
Request URL:
POST /v1/mfa/devices
Response example:
After receiving this request, Solaris verifies the customer's information and creates a temporary, unverified device with a unique id
. Afterward, Solaris sends the following to verify the device:
- A six-digit one-time password (OTP) sent via SMS to the customer's registered mobile number.
- A signature challenge on the SMS code that is valid for five minutes with a unique
id
.
{
"id": "string",
"key_id": "string",
"challenge":
{
"id": "string",
"type": "signature",
"created_at": "2019-08-21T12:16:17Z",
"expires_at": "2019-08-21T12:21:17Z"
}
}
Click here to view the full API reference.
This method retrieves information about an existing bound device.
Request URL:
GET /v1/mfa/devices/{id}
Response example:
{
"id": "string",
"name": "Samsung Galaxy S10",
"person_id": "dc1a6812a14f6cc338cd084208535bcdcper",
"created_at": "string",
"deleted_at": null
}
Click here to view the full API reference.
This endpoint deletes an existing bound device associated with a specific customer.
Request URL:
DELETE /v1/mfa/devices/{id}
Click here to view the full API reference.
This endpoint retrieves the details of the signature challenge generated after creating a device. The challenge is valid for 5 minutes.
Request URL:
GET /v1/mfa/challenges/signatures/{signature_id}
Response example:
{
"created_at": "2019-08-21T12:16:17Z",
"type": "sms",
"id": "string",
"expires_at": "2019-08-21T12:21:17Z"
}
Click here to view the full API reference.
Once they receive the six-digit OTP, the customer must enter it in your app along with the private key to create a signature
. Then, you must call the following endpoint to verify the signature
. The signature
is the input code delivered with the SMS and provided by the customer.
How to create the signature:
- Create a hash (SHA256) with the OTP.
- Sign the hash with the private key.
- Encode the signature in
ASN.1
format. - Hex encode the
ASN.1
format signature. - Send the hex-encoded signature in the request payload.
This method verifies the signature created by the customer.
Request URL:
PUT /v1/mfa/challenges/signatures/{id}
Response example:
HTTP/1.1 204 Challenge successful
Click here to view the full API reference.
After a successful device binding, the customer can create additional keys (either restricted or unrestricted) and add them to the device.
This endpoint adds a new restricted
or unrestricted
key to an existing device.
How to encode the public key:
- Generate a public/private key pair (ECC curve name: ECDSA-P256).
- Hex encode the raw public key.
Request attributes
Attribute | Type | Description |
---|---|---|
key | string | The new hex-encoded public key created on the customer's bound device. |
key_type | string | Type of key pair. Possible values are ecdsa-p256 . |
key_purpose | string | Purpose of the key. Possible values are restricted or unrestricted . |
device_signature | object | Object containing the information about the previously registered key and the signature of the new key. |
signature_key_purpose | string | Purpose of the previously registered key used to sign the new key. Possible values are restricted or unrestricted . |
signature | string | Signature of the new key to be added signed with the previously registered private key on the same device. signature_new_key = registered_private_key.sign(hashSHA256(new_public_key) |
Request URL
POST /mfa/devices/{id}/keys
Example response
HTTP/1.1 201 Created
{
"id": "20f892fdc6414320b5b1df612f833edb"
}
Click here to view the full API reference.
This endpoint retrieves a specific key linked to a device.
Request URL
GET /mfa/devices/{id}/keys/{key_id}
Example response
{
"key_id": "3e1415b8-901d-4c1a-8950-f3a1083c6c3b",
"key_purpose": "unrestricted",
"key_type": "ecdsa-p256",
"used_at": "2022-03-18T14:55:04Z"
}
Click here to view the full API reference.
This endpoint retrieves all keys linked to a device.
Request URL
GET /mfa/devices/:{id}/keys
Example response
[
{
"device_id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
"person_id": "ec3d16cbc106f481b72d881d90c89cc5cper",
"name": "Test device",
"created_at": "2022-03-18T14:50:04Z",
"deleted_at": "2022-04-18T14:55:04Z",
"keys": [
{
"key_id": "3e1415b8-901d-4c1a-8950-f3a1083c6c3b",
"key_purpose": "unrestricted",
"used_at": "2022-03-18T14:55:04Z"
}
]
}
]