Device binding

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This guide explains the device binding feature, including the key concepts and endpoints required to implement it. Device binding is mandatory for all secure flows, such as those requiring a Qualified Electronic Signature (QES) or two-factor authentication (e.g., BankIdentPlus).

Overview

The device binding API allows customers to register their devices and create public/private key pairs for authenticating Multi-Factor Authentication (MFA) challenges.

Device binding is a prerequisite for Strong Customer Authentication (SCA). It ensures that a request originates from a trusted, registered device.

Once a customer binds their device, they receive authentication challenges that they must confirm using that device (e.g., logging in, changing data, authorizing transactions).

Restricted vs. Unrestricted keys

Customers authorize actions using one of two key types:

• Unrestricted keys: Do not require specific user authentication to sign a request. These are typically used for background processes or low-risk actions.
• Restricted keys: Require user authentication via biometrics (e.g., Touch ID, Face ID) to access the private key.
  • iOS: Combine privateKeyUsageflag with userPresence or touchIDAny.
  • Android: Use setUserAuthenticationParameters().

See the Strong customer authentication guide for the full list of use cases requiring restricted vs. unrestricted keys.

Security requirements

Your implementation must meet the following security standards:

• Limit: Maximum of five registered devices per customer.
• OS: Android 8.0+ or iOS 12+.
• Hardware: Must support hardware-backed security via separate execution environments (e.g., Secure Enclave in iOS, TEE in Android).
• Access Control: Your app must enforce a device passcode or biometric lock.
• Storage: You must store personalized security credentials and cryptographic keys in the secure environment.

Integration flow

Solaris supports two methods for device binding. You must choose the method that fits your use case and platform requirements:

• SMS OTP (Default): Solaris sends a one-time password to the customer's verified mobile number.
• Activation Code (QR): You generate an activation code, convert it to a QR code, and deliver it to the customer (e.g., via snail mail or a secure web interface).

Flow 1: SMS Binding

Flow 2: Activation Code (QR) Binding

In this flow, you must manage the lifecycle of the activation code before the customer can bind their device. This method allows customers to bind a new device even if they have lost access to their previously bound device.

Implementation

Select the binding method you wish to implement to see the specific steps.

Integration steps

1. Initiation: The customer enters device information in your app.
2. Key Generation: Your app generates a private/public key pair in ecdsa-p256 format.
3. Submission: Send the public key (hex-encoded) and device info to Solaris via POST Create device.
4. Challenge: Solaris triggers a verification flow based on your challenge_type:
   • SMS: Solaris sends a 6-digit OTP via SMS to the customer.
   • QR: Solaris validates the Activation Code logic (no SMS is sent).
5. Input: The customer provides the verification data:
   • SMS: Customer enters the 6-digit OTP.
   • QR: Customer scans the QR code to extract the Activation Code string.
6. Signing: Your app creates a signature using the Private Key and the input data (OTP or Activation Code).
7. Verification: Send the signature to Solaris via PUT Verify the signature.
8. Completion: If valid, Solaris registers the device.

POST /v1/mfa/devices

{
  "person_id": "ec3d16cbc106f481b72d881d90c89cc5cper",
  "key_type": "ecdsa-p256",
  "key": "04a346c447...",
  "key_purpose": "unrestricted",
  "name": "iPhone 13",
  "challenge_type": "sms"
}

PUT /v1/mfa/challenges/signatures/{id}

Post-binding: Manage keys

After successful binding (via either method), you can add more keys to the device. This is useful if you want to separate keys for different permission levels (e.g., Restricted vs. Unrestricted).

POST Add new key to device

To add a new key, you must sign the request using the existing verified private key.

Request URL

POST /mfa/devices/{id}/keys

• API Reference: Add Key

Manage device keys

• GET Retrieve a specific key
• GET Retrieve all keys for a device

Testing in Sandbox

In the Sandbox environment, you cannot generate real QR codes or send physical mail. Use these static activation codes to simulate specific scenarios when calling PUT /v1/mfa/challenges/signatures/{id}.