Device management (1.0)

Download OpenAPI specification:Download

Device binding

Create a new device binding

This endpoint initiates the device binding process for registering a device for a customer. 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.

Request
Security:
Request Body schema: application/json
person_id
string

ID of the person for whom the device should be registered.

key_type
string

The type of key pair used for verifying the device and, after registration, for device signing. At this time, only ecdsa-p256 is supported.

Value: "ecdsa-p256"
challenge_type
string

(Optional) The type of challenge to use in order to verify the device. Default value is sms.

key
string

The hex-encoded public key generated by the device to be registered.

key_purpose
string
Default: "unrestricted"

The purpose of the key that will be used to sign for the device. Possible values are unrestricted (default) and restricted.

Enum: "unrestricted" "restricted"
name
string

Specify a name for the new device.

object

(For SMS challenges) Specifies additional info for processing the SMS challenge.

language
string

The language to use in the SMS challenge. Options are: de, en, fr.

Enum: "de" "en" "fr"
device_data
string

Any device-specific string provided by the calling client.

Responses
202

Created

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

409

Conflict

500

Internal server error

post/v1/mfa/devices
Request samples
application/json
{
  • "person_id": "ec3d16cbc106f481b72d881d90c89cc5cper",
  • "key_type": "ecdsa-p256",
  • "challenge_type": "string",
  • "key": "04a346c447bac867d15a0a0f555eece87b416ba6f917df1e39f1cba7515757b4da9eaf5f1604f7e47f1948af3b34ed2735aa565cfd97d5361e12b3b8603bdad73c",
  • "key_purpose": "unrestricted",
  • "name": "Test device",
  • "sms_challenge": {
    },
  • "language": "en",
  • "device_data": "YW55IHN0cmluZyBwcm92aWRlZCBieSB0aGUgY2xpZW50Cg=="
}
Response samples
application/json
{
  • "id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
  • "key_id": "3e1415b8-901d-4c1a-8950-f3a1083c6c3b",
  • "challenge": {
    }
}

List bound devices

Returns a list of devices that your customers have verified using the device binding process.

Request
Security:
query Parameters
page[size]
integer

Use this filter to specify the size of each page of results.

page[number]
integer

Use this filter to return only the devices on a certain page of the response.

filter[person_id]
string

Use this filter to return only devices that belong to a specific person.

filter[include_deleted]
string

Boolean value that determines whether or not the API should also return deleted devices. Default value is false.

Responses
200

OK

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

409

Conflict

500

Internal server error

get/v1/mfa/devices
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/mfa/devices?page%5Bsize%5D=0&page%5Bnumber%5D=0&filter%5Bperson_id%5D=string&filter%5Binclude_deleted%5D=string'
Response samples
application/json
[
  • {
    }
]

Retrieve a bound device

Retrieves a single device that a customer registered using the device binding process.

Request
Security:
path Parameters
id
required
string
Responses
200

OK

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

409

Conflict

500

Internal server error

get/v1/mfa/devices/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/mfa/devices/{id}'
Response samples
application/json
{
  • "id": "20f892fdc6414320b5b1df612f833edb",
  • "name": "Samsung Galaxy S20",
  • "person_id": "83caf49280604836bdbb41ba33d8cper",
  • "created_at": "2022-06-30T22:19:37Z",
  • "deleted_at": "string"
}

Delete a device

Removes a device from Solaris' system. This endpoint triggers the deletion of all keys associated with the device.

Request
Security:
path Parameters
id
required
string
Responses
204

No Content

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

409

Conflict

500

Internal server error

delete/v1/mfa/devices/{id}
Request samples
curl -i -X DELETE \
  'https://api.solaris-sandbox.de/v1/mfa/devices/{id}'
Response samples
application/json
{
  • "title": "Failed to build pagination headers.",
  • "status": "400",
  • "id": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  • "detail": "Cannot connect to database.",
  • "code": "build_pagination_headers_failure"
}

Retrieve a device binding signature challenge

Returns a signature challenge created during the device binding process.

Request
Security:
path Parameters
id
required
string
Responses
200

OK

400

Validation error

401

Unauthorized

403

No access

404

Not found

409

Conflict

500

Internal server error

get/v1/mfa/challenges/signatures/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/mfa/challenges/signatures/{id}'
Response samples
application/json
{
  • "id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
  • "type": "signature",
  • "created_at": "2022-03-18T14:50:04Z",
  • "expires_at": "2022-03-18T14:55:04Z"
}

Verify device binding signature challenge

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. 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.

Request
Security:
path Parameters
id
required
string
Request Body schema: application/json
signature
string

The hex-encoded signature for the challenge.

device_data
string

Any device-specific string provided by the calling client.

Responses
204

Challenge successful

400

Validation error

401

Unauthorized

403

No access

404

Not found

409

Conflict

500

Internal server error

put/v1/mfa/challenges/signatures/{id}
Request samples
application/json
{
  • "signature": "3045022100bdbebd8ba5e4ea23a4ab3d852cbf0968cbc7319c7c4388e0c54bf34e896d19d802205880fca38bf5450bff73d41c675e1444b8e3c75dc8bf764d5c0e9282bd150ade",
  • "device_data": "YW55IHN0cmluZyBwcm92aWRlZCBieSB0aGUgY2xpZW50Cg=="
}
Response samples
application/json
{
  • "title": "Failed to build pagination headers.",
  • "status": "400",
  • "id": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  • "detail": "Cannot connect to database.",
  • "code": "build_pagination_headers_failure"
}

Add new key to a bound device

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.

Request
Security:
path Parameters
id
required
string
Request Body schema: application/json
key
string

The hex-encoded public key generated on the registered device.

key_type
string

The type of key pair used for verifying the device and, after registration, for device signing. At this time, only ecdsa-p256 is supported.

Value: "ecdsa-p256"
key_purpose
string

The purpose of the key that will be used to sign for the device. Possible values are unrestricted (default) and restricted.

Enum: "unrestricted" "restricted"
object

Contains information about the existing key registered for the device.

device_data
string

Any device-specific string provided by the calling client.

Responses
201

Created

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

409

Conflict

500

Internal server error

post/v1/mfa/devices/{id}/keys
Request samples
application/json
{
  • "key": "04a346c447bac867d15a0a0f555eece87b416ba6f917df1e39f1cba7515757b4da9eaf5f1604f7e47f1948af3b34ed2735aa565cfd97d5361e12b3b8603bdad73c",
  • "key_type": "ecdsa-p256",
  • "key_purpose": "restricted",
  • "device_signature": {
    },
  • "device_data": "YW55IHN0cmluZyBwcm92aWRlZCBieSB0aGUgY2xpZW50Cg=="
}
Response samples
application/json
{
  • "id": "string"
}

List all keys for a bound device

Retrieves a list of all registered keys associated with a device registered to a customer through the device binding process.

Request
Security:
path Parameters
id
required
string
Responses
200

OK

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

500

Internal server error

get/v1/mfa/devices/{id}/keys
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/mfa/devices/{id}/keys'
Response samples
application/json
[
  • {
    }
]

Retrieve a specific key registered to a bound device

Returns a key associated with a specific device that was previously registered using the device binding process.

Request
Security:
path Parameters
id
required
string

ID of the device that the key is associated with.

key_id
required
string

ID of the key to retrieve.

Responses
200

OK

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

500

Internal server error

get/v1/mfa/devices/{id}/keys/{key_id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/mfa/devices/{id}/keys/{key_id}'
Response samples
application/json
{
  • "key_id": "3e1415b8-901d-4c1a-8950-f3a1083c6c3b",
  • "key_purpose": "unrestricted",
  • "key_type": "ecdsa-p256",
  • "used_at": "2022-03-18T14:55:04Z"
}

Device signing challenges

Create device signing challenge

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.

Request
Security:
Request Body schema: application/json
device_id
string

The ID of the customer's previously registered/bound device.

key_purpose
string
Default: ""

(Optional) Specifies the type of key to be used for signing the device challenge (restricted or unrestricted). Please note the following: - If you do not enter a value here, then the key will be chosen using pre-defined strategy. - If a device has more than one registered key pair, the default value would be unrestricted.

Enum: "" "unrestricted" "restricted"
device_data
string

Any device-specific string provided by the calling client.

Responses
201

Created

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

409

Conflicts

500

Internal server error

post/v1/mfa/challenges/devices
Request samples
application/json
{
  • "device_id": "db12eeccbf4548cb9011b3085094c14a",
  • "key_purpose": "unrestricted",
  • "device_data": "YW55IHN0cmluZyBwcm92aWRlZCBieSB0aGUgY2xpZW50Cg=="
}
Response samples
application/json
{
  • "id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
  • "type": "signature",
  • "created_at": "2022-03-18T14:50:04Z",
  • "expires_at": "2022-03-18T14:55:04Z",
  • "string_to_sign": "string"
}

Retrieve a device signing challenge

Returns an existing device signing challenge.

Request
Security:
path Parameters
id
required
string
Responses
200

OK

400

Validation error

401

Unauthorized

403

No access

404

Not found

409

Conflict

500

Internal server error

get/v1/mfa/challenges/devices/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/mfa/challenges/devices/{id}'
Response samples
application/json
{
  • "id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
  • "type": "signature",
  • "created_at": "2022-03-18T14:50:04Z",
  • "expires_at": "2022-03-18T14:55:04Z",
  • "string_to_sign": "string"
}

Verify device signing challenge

Verifies the customer's device signature to complete a device signing challenge.

Request
Security:
path Parameters
id
required
string
Request Body schema: application/json
signature
string

The raw hex-encoded signature for the challenge.

device_data
string

Any device-specific string provided by the calling client.

Responses
204

Challenge successful

400

Validation error

401

Unauthorized

403

No access

404

Not found

409

Conflict

500

Internal server error

put/v1/mfa/challenges/devices/{id}
Request samples
application/json
{
  • "signature": "3045022100bdbebd8ba5e4ea23a4ab3d852cbf0968cbc7319c7c4388e0c54bf34e896d19d802205880fca38bf5450bff73d41c675e1444b8e3c75dc8bf764d5c0e9282bd150ade",
  • "device_data": "YW55IHN0cmluZyBwcm92aWRlZCBieSB0aGUgY2xpZW50Cg=="
}
Response samples
application/json
{
  • "title": "Failed to build pagination headers.",
  • "status": "400",
  • "id": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  • "detail": "Cannot connect to database.",
  • "code": "build_pagination_headers_failure"
}

SMS challenges

Create an SMS challenge

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.

Request
Security:
Request Body schema: application/json
person_id
string

ID of the person who should receive the SMS challenge.

device_data
string

Any device-specific string provided by the calling client.

Responses
202

Accepted

400

Validation error

401

Unauthorized

403

Forbidden

404

Not found

409

Conflict

500

Internal server error

post/v1/mfa/challenges/sms
Request samples
application/json
{
  • "person_id": "ec3d16cbc106f481b72d881d90c89cc5cper",
  • "device_data": "YW55IHN0cmluZyBwcm92aWRlZCBieSB0aGUgY2xpZW50Cg=="
}
Response samples
application/json
{
  • "id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
  • "type": "signature",
  • "created_at": "2022-03-18T14:50:04Z",
  • "expires_at": "2022-03-18T14:55:04Z"
}

Retrieve an SMS challenge

Returns a previously created SMS challenge.

Request
Security:
path Parameters
id
required
string
Responses
200

OK

400

Validation error

401

Unauthorized

403

No access

404

Not found

409

Conflict

500

Internal server error

get/v1/mfa/challenges/sms/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/mfa/challenges/sms/{id}'
Response samples
application/json
{
  • "id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
  • "type": "signature",
  • "created_at": "2022-03-18T14:50:04Z",
  • "expires_at": "2022-03-18T14:55:04Z"
}

Verify SMS OTP

Verifies the SMS OTP sent to a customer's mobile number as part of an SMS challenge.

Request
Security:
path Parameters
id
required
string
Request Body schema: application/json
code
string

The SMS OTP that was sent to the customer's mobile number as part of the SMS challenge.

device_data
string

Any device-specific string provided by the calling client.

Responses
204

Code challenge successful

400

Validation error

401

Unauthorized

403

No access

404

Not found

409

Conflict

500

Internal server error

put/v1/mfa/challenges/sms/{id}
Request samples
application/json
{
  • "code": "123456",
  • "device_data": "YW55IHN0cmluZyBwcm92aWRlZCBieSB0aGUgY2xpZW50Cg=="
}
Response samples
application/json
{
  • "title": "Failed to build pagination headers.",
  • "status": "400",
  • "id": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  • "detail": "Cannot connect to database.",
  • "code": "build_pagination_headers_failure"
}

Change requests

Request authorization for a change request

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.

Request
Security:
path Parameters
change_request_id
required
string
Request Body schema: application/json

The content of the request.

delivery_method
string

The method to use for delivering the authorization challenge.

Enum: "mobile_number" "device_binding" "device_signing"
person_id
string

The person to whom the SMS OTP should be sent. Only include this property if the delivery_method is mobile_number.

device_id
string

ID of the device used for authorization

device_data
string

Encoded device data as provided by Seon SDK.

Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

post/v1/change_requests/{change_request_id}/authorize
Request samples
application/json
{
  • "delivery_method": "mobile_number",
  • "person_id": "69c673883853eafb2da9157de2bdaa05cper",
  • "device_data": "ewogICJpcCI6ICIxMjcuMC4wLjEhCn0="
}
Response samples
application/json
{
  • "id": "b520ce9090c44a989149fe7f2f94a785",
  • "string_to_sign": "3045022100bdbebd8ba5e4ea23a4ab3d852cbf0968cbc7319c7c4388e0c54bf34e",
  • "status": "AUTHORIZATION_REQUIRED",
  • "updated_at": "2021-12-22T15:05:33.634+00:00"
}

Confirm change request authorization

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.

Request
Security:
path Parameters
change_request_id
required
string
Request Body schema: application/json

The content of the request.

device_id
string

(If the delivery_method was device_signing) The ID of the customer's bound device used for authorization.

signature
string

(If the delivery_method was device_signing) The hex-encoded signature generated by signing the text_to_sign with the device's public key.

person_id
string

(If the delivery_method was mobile_number) The ID of the person who received the SMS OTP for authorization.

tan
string

(If the delivery_method was mobile_number) The six-digit OTP value that the person received via SMS.

Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

422

Signature verification failure.

500

Internal server error.

default

Unexpected error

post/v1/change_requests/{change_request_id}/confirm
Request samples
application/json
{
  • "person_id": "69c673883853eafb2da9157de2bdaa05cper",
  • "tan": "123456"
}
Response samples
application/json
{
  • "id": "b520ce9090c44a989149fe7f2f94a785",
  • "status": "COMPLETED",
  • "updated_at": "2021-12-22T15:05:33.634+00:00",
  • "response_body": {
    },
  • "response_code": 202
}