# Device management Version: 1.0 ## Servers Sandbox ``` https://api.solaris-sandbox.de ``` Production ``` https://api.solarisbank.de ``` ## Download OpenAPI description [Device management](https://docs.solarisgroup.com/_bundle/api-reference/onboarding/device-management.yaml) ## Device binding ### Create a new device binding - [POST /v1/mfa/devices](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1devices/post.md): This endpoint initiates the device binding process for registering a device for a customer. There are two ways to bind a device. The option depends on the vaue in challenge_type. i. Using SMS OTP. When the request is processed, Solaris sends an SMS OTP to the customer's registered mobile number. Before you can use this endpoint, your customer must have a verified mobile number. ii. Using activation code. To use this option, create an activation challenge for the customer and ensure the code in the challenge is delivered to the customer already. Refer Activation challenges endpoints. ### List bound devices - [GET /v1/mfa/devices](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1devices/get.md): Returns a list of devices that your customers have verified using the device binding process. ### Retrieve a bound device - [GET /v1/mfa/devices/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D/get.md): Retrieves a single device that a customer registered using the device binding process. ### Delete a device - [DELETE /v1/mfa/devices/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D/delete.md): Removes a device from Solaris' system. This endpoint triggers the deletion of all keys associated with the device. ### Retrieve a device binding signature challenge - [GET /v1/mfa/challenges/signatures/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1challenges~1signatures~1%7Bid%7D/get.md): Returns a signature challenge created during the device binding process. ### Verify device binding signature challenge - [PUT /v1/mfa/challenges/signatures/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1challenges~1signatures~1%7Bid%7D/put.md): Verifies the signature from a customer's device in order to verify their ownership of the device. To create the signature: 1. Create a hash (SHA256) with the OTP/activation_code. 2. Sign the hash with the private key. 3. Encode the signature in ASN.1 format. 4. Hex-encode the ASN.1-formatted signature. 5. Send the signature in the request body. ### Add new key to a bound device - [POST /v1/mfa/devices/{id}/keys](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D~1keys/post.md): Adds a new public key to a device that was previously registered by a customer using the device binding process. The new key must have a different purpose than the existing key. E.g., if the device already has an unrestricted key, then the new key must be restricted. ### List all keys for a bound device - [GET /v1/mfa/devices/{id}/keys](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D~1keys/get.md): Retrieves a list of all registered keys associated with a device registered to a customer through the device binding process. ### Retrieve a specific key registered to a bound device - [GET /v1/mfa/devices/{id}/keys/{key_id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D~1keys~1%7Bkey_id%7D/get.md): Returns a key associated with a specific device that was previously registered using the device binding process. ## Device signing challenges ### Create device signing challenge - [POST /v1/mfa/challenges/devices](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-signing-challenges/paths/~1v1~1mfa~1challenges~1devices/post.md): This endpoint creates a new device signing 2FA challenge on a customer's device. The customer must already have registered the device using the device binding process. ### Retrieve a device signing challenge - [GET /v1/mfa/challenges/devices/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-signing-challenges/paths/~1v1~1mfa~1challenges~1devices~1%7Bid%7D/get.md): Returns an existing device signing challenge. ### Verify device signing challenge - [PUT /v1/mfa/challenges/devices/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/device-signing-challenges/paths/~1v1~1mfa~1challenges~1devices~1%7Bid%7D/put.md): Verifies the customer's device signature to complete a device signing challenge. ## SMS challenges ### Create an SMS challenge - [POST /v1/mfa/challenges/sms](https://docs.solarisgroup.com/api-reference/onboarding/device-management/sms-challenges/paths/~1v1~1mfa~1challenges~1sms/post.md): This endpoint creates a 2FA challenge for the customer specified in the request body. Once the request has been processed, the customer will receive an SMS at their verified mobile number. ### Retrieve an SMS challenge - [GET /v1/mfa/challenges/sms/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/sms-challenges/paths/~1v1~1mfa~1challenges~1sms~1%7Bid%7D/get.md): Returns a previously created SMS challenge. ### Verify SMS OTP - [PUT /v1/mfa/challenges/sms/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/sms-challenges/paths/~1v1~1mfa~1challenges~1sms~1%7Bid%7D/put.md): Verifies the SMS OTP sent to a customer's mobile number as part of an SMS challenge. ## Change requests ### Request authorization for a change request - [POST /v1/change_requests/{change_request_id}/authorize](https://docs.solarisgroup.com/api-reference/onboarding/device-management/change-requests/paths/~1v1~1change_requests~1%7Bchange_request_id%7D~1authorize/post.md): This endpoint initiates an SMS OTP or device signing challenge to authorize a change request. For SMS OTP challenges: include the person_id of the person to whom the SMS challenge should be sent in the body of the request. This person must have a verified mobile number. If the change request relates to a change on a business, then the person must have the necessary role to authorize the change request. For device signing challenges: Include the device_id of the device to use for authorizing the change request. This device must already be registered via the device binding process. ### Confirm change request authorization - [POST /v1/change_requests/{change_request_id}/confirm](https://docs.solarisgroup.com/api-reference/onboarding/device-management/change-requests/paths/~1v1~1change_requests~1%7Bchange_request_id%7D~1confirm/post.md): Confirms a change request by validating an SMS OTP or device signature provided by the customer. Your solution must collect either the OTP or the signature from the customer in its frontend after calling the POST Request authorization for a change request method. When the change request is successfully confirmed, the response will include metadata around the created/updated resource, a response_body with its properties, and the relevant response_code for the creation/update operation. Note: If the delivery_method of the change request authorization was static (i.e., for testing purposes), then set the value of tan to 212212. ## Activation challenges ### Create an Activation challenge - [POST /v1/mfa/challenges/activation](https://docs.solarisgroup.com/api-reference/onboarding/device-management/activation-challenges/paths/~1v1~1mfa~1challenges~1activation/post.md): Generate a new activation code that can be delivered to endcustomer by the partner. ### List Activation Challenges for a person - [GET /v1/mfa/challenges/activation](https://docs.solarisgroup.com/api-reference/onboarding/device-management/activation-challenges/paths/~1v1~1mfa~1challenges~1activation/get.md): Returns a list of activation challenges based on the filter criterias. ### Retrieve an Activation challenge - [GET /v1/mfa/challenges/activation/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/activation-challenges/paths/~1v1~1mfa~1challenges~1activation~1%7Bid%7D/get.md): Returns a previously created activation challenge. ### Delete an Activation challenge - [DELETE /v1/mfa/challenges/activation/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/activation-challenges/paths/~1v1~1mfa~1challenges~1activation~1%7Bid%7D/delete.md): Marks an activation challenge as expired so that it cannot be used anymore. ### Create a delivery event for an activation challenge - [POST /v1/mfa/challenges/activation/{id}/delivery_events](https://docs.solarisgroup.com/api-reference/onboarding/device-management/activation-challenges/paths/~1v1~1mfa~1challenges~1activation~1%7Bid%7D~1delivery_events/post.md): Registers a new delivery event that updates the delivery status of an activation challenge. ### List delivery events for an activation challenge. - [GET /v1/mfa/challenges/activation/{id}/delivery_events](https://docs.solarisgroup.com/api-reference/onboarding/device-management/activation-challenges/paths/~1v1~1mfa~1challenges~1activation~1%7Bid%7D~1delivery_events/get.md): Returns a list delivery events for a given activation challenge (sorted descending by timestamp). ### Retrieve a delivery event. - [GET /v1/mfa/challenges/activation/{activation_challenge_id}/delivery_events/{id}](https://docs.solarisgroup.com/api-reference/onboarding/device-management/activation-challenges/paths/~1v1~1mfa~1challenges~1activation~1%7Bactivation_challenge_id%7D~1delivery_events~1%7Bid%7D/get.md): Returns an activation challenge delivery event.