API docs by Redocly

Fraud Management Interface (2.15.0)

Download OpenAPI specification:Download

E-mail: support@build38.com

CYWALL Cloud Fraud Management Interface

custom-key

The Custom Key API

Generate Custom Key

Creates a Custom Key with input algorithm and length, and attaches it to a cywallId

header Parameters
X-Cert-Client-serialNumber
string

The serial number cert header in hexadecimal to verify against the input cywallId.

X-Cert-Client-decimalSerialNumber
integer

The serial number cert header in decimal to verify against the input cywallId.

Request Body schema: application/json
required

Contains the information of the key to generate as well as the cywallId whose request is being processed.

cywallId
required
string <uuid>

This is the cywallId of the lib instance that is requesting a new Custom Key. Do note that requesting a Custom Key for a deprecated cywallId (a re-register operation deprecates a working cywallId in favor of a new cywallId) will be denied. In case it is required, the Verify endpoint can be used to get the new cywallId through the 'supersededBy' field.

keyAlgorithm
required
string
Enum: "AES" "RSA" "ECC_NIST"

This is the algorithm used by the new Custom Key.

keyLength
required
integer <int32>

This is the length of the new Custom Key.

Responses

Request samples

Content type
application/json
{
  • "cywallId": "ab18be90-4913-4422-b1a6-63e2c0151289",
  • "keyAlgorithm": "AES",
  • "keyLength": 256
}

Fraud Management

Allows updates of current status of an instance (specified by the CYWALL ID)

This request requires TLS client authentication, which means that the certificate and the private key must be configured before performing the call. Check CYWALL Developer's Guide for further details on how to configure client authentication.

path Parameters
cywallId
required
string <uuid>

The CYWALL ID of the device whose status is requested to change. E.g.: cc7cdd0a-e3c9-488a-9a09-789e862fcc7c

status
required
string
Enum: "LOCK_REQUEST" "UNLOCK_REQUEST" "WIPE_REQUEST"

The new status requested for the CYWALL id supplied. E.g.: LOCK_REQUEST

header Parameters
X-Cert-Client-serialNumber
string

The serial number cert header in hexadecimal to verify against the input cywallId.

X-Cert-Client-decimalSerialNumber
integer

The serial number cert header in decimal to verify against the input cywallId.

Responses

Returns verification information on the selected device (specified by the CYWALL ID)

This request requires TLS client authentication, which means that the certificate and the private key must be configured before performing the call. Check CYWALL Developer's Guide for further details on how to configure client authentication.

path Parameters
cywallId
required
string <uuid>

The CYWALL ID of the device whose status is queried. E.g.: cc7cdd0a-e3c9-488a-9a09-789e862fcc7c

query Parameters
include_matches
boolean
Default: false

Set to "true" in order to include information about other CYWALL instances running on the same device. The default value is "false".

include_device_info
boolean
Default: false

Set to "true" in order to include device hardware and software information. The default value is "false".

header Parameters
X-Cert-Client-serialNumber
string

The serial number cert header in hexadecimal to verify against the input cywallId.

X-Cert-Client-decimalSerialNumber
integer

The serial number cert header in decimal to verify against the input cywallId.

Responses

Response samples

Content type
application/json
{
  • "supersededBy": "e8c122fd-1251-4208-99e6-8b91eaa31720",
  • "state": "VALID",
  • "userLink": "C1991F9EAF989B6DA1AC4176E2FB22024EA1BC31BC3A069880DFB8A75f305EC",
  • "deviceRti": {
    },
  • "timestamp": "2019-08-21T16:13:44.902+02:00",
  • "trustLevel": 1,
  • "accountsSeenOnDevice": {
    },
  • "deviceInfo": {
    }
}

Allows updates of current status of an instance (specified by the CYWALL ID)

This request requires TLS client authentication, which means that the certificate and the private key must be configured before performing the call. Check CYWALL Developer's Guide for further details on how to configure client authentication.

path Parameters
cywallId
required
string <uuid>

The CYWALL ID of the device whose status is requested to change. E.g.: cc7cdd0a-e3c9-488a-9a09-789e862fcc7c

status
required
string
Enum: "LOCK_REQUEST" "UNLOCK_REQUEST" "WIPE_REQUEST"

The new status requested for the CYWALL id supplied. E.g.: LOCK_REQUEST

header Parameters
X-Cert-Client-serialNumber
string

The serial number cert header in hexadecimal to verify against the input cywallId.

X-Cert-Client-decimalSerialNumber
integer

The serial number cert header in decimal to verify against the input cywallId.

Responses

Returns verification information on the selected device (specified by the CYWALL ID)

This request requires TLS client authentication, which means that the certificate and the private key must be configured before performing the call. Check CYWALL Developer's Guide for further details on how to configure client authentication.

path Parameters
cywallId
required
string <uuid>

The CYWALL ID of the device whose status is queried. E.g.: cc7cdd0a-e3c9-488a-9a09-789e862fcc7c

query Parameters
include_matches
boolean
Default: false

Set to "true" in order to include information about other CYWALL instances running on the same device. The default value is "false".

include_device_info
boolean
Default: false

Set to "true" in order to include device hardware and software information. The default value is "false".

header Parameters
X-Cert-Client-serialNumber
string

The serial number cert header in hexadecimal to verify against the input cywallId.

X-Cert-Client-decimalSerialNumber
integer

The serial number cert header in decimal to verify against the input cywallId.

Responses

Response samples

Content type
application/json
{
  • "supersededBy": "e8c122fd-1251-4208-99e6-8b91eaa31720",
  • "state": "VALID",
  • "userLink": "C1991F9EAF989B6DA1AC4176E2FB22024EA1BC31BC3A069880DFB8A75f305EC",
  • "deviceRti": {
    },
  • "timestamp": "2019-08-21T16:13:44.902+02:00",
  • "trustLevel": 1,
  • "accountsSeenOnDevice": {
    },
  • "deviceInfo": {
    }
}

custom-key-controller

getSecureKey

path Parameters
cywallId
required
string <uuid>
query Parameters
key_label
required
string
header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string
X-Cert-Client-decimalSerialNumber
integer <int32>

Responses

generateCustomKey_DFP

header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string

The serial number cert header in hexadecimal to verify against the input cywallId.

X-Cert-Client-decimalSerialNumber
integer

The serial number cert header in decimal to verify against the input cywallId.

Request Body schema: application/json
required

Contains the information of the key to generate as well as the cywallId whose request is being processed.

cywallId
required
string <uuid>
keyAlgorithm
required
string
keyLength
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "cywallId": "c4769d29-cd40-479f-949d-f7f16a34ae51",
  • "keyAlgorithm": "string",
  • "keyLength": 0
}

random-generator-controller

randomGenerator

query Parameters
length
required
integer <int32>
header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string
X-Cert-Client-decimalSerialNumber
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "secureRandom": "string"
}

registration-controller

register

header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string
X-Cert-Client-decimalSerialNumber
integer <int32>
Request Body schema: application/json
required
userLink
required
string
required
object (SPApplication)
spId
required
string <uuid>
clientCsr
string
object
required
object
required
object
required
object
dfpHashType
required
integer <int32>
required
object (Version)
object
Array of objects (DeviceAlertsInfo)

Responses

Request samples

Content type
application/json
{
  • "userLink": "string",
  • "application": {
    },
  • "spId": "2da8e569-d316-405d-a035-a5d0d2e437c4",
  • "clientCsr": "string",
  • "keyInfo": {
    },
  • "deviceId": {
    },
  • "softId": {
    },
  • "deviceRti": {
    },
  • "dfpHashType": 0,
  • "cywallVersion": {
    },
  • "deviceInfo": {
    },
  • "deviceAlertsInfoList": [
    ]
}

Response samples

Content type
application/json
{
  • "clientCert": "string",
  • "clientPrK": {
    },
  • "clientKSK": {
    },
  • "cywallId": "c4769d29-cd40-479f-949d-f7f16a34ae51"
}

registration-controller-jws

register_1

header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string
X-Cert-Client-decimalSerialNumber
integer <int32>
X-Cert-Client
required
string
Request Body schema: text/plain
required
string

Responses

update-controller

update

path Parameters
cywallId
required
string <uuid>
header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string
X-Cert-Client-decimalSerialNumber
integer <int32>
Request Body schema: application/json
required
required
object
required
object
required
object
required
object (Version)
object

Responses

Request samples

Content type
application/json
{
  • "deviceId": {
    },
  • "deviceRti": {
    },
  • "softId": {
    },
  • "cywallVersion": {
    },
  • "deviceInfo": {
    }
}

Response samples

Content type
application/json
{
  • "rc": "string"
}

validation-controller

validate

path Parameters
cywallId
required
string <uuid>
header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string
X-Cert-Client-decimalSerialNumber
integer <int32>
Request Body schema: application/json
required
required
object (SPApplication)
deviceId
required
Array of strings [ 1 .. 2147483647 ] items
hash
required
string
required
object
required
object
required
object (Version)
object
Array of objects (DeviceAlertsInfo)

Responses

Request samples

Content type
application/json
{
  • "application": {
    },
  • "deviceId": [
    ],
  • "hash": "string",
  • "softId": {
    },
  • "deviceRti": {
    },
  • "cywallVersion": {
    },
  • "deviceInfo": {
    },
  • "deviceAlertsInfoList": [
    ]
}

Response samples

Content type
application/json
{
  • "rc": "string",
  • "missingIds": [
    ]
}

update-controller-jws

update_1

path Parameters
cywallId
required
string <uuid>
header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string
X-Cert-Client-decimalSerialNumber
integer <int32>
X-Cert-Client
required
string
Request Body schema: text/plain
required
string

Responses

validation-controller-jws

validate_1

path Parameters
cywallId
required
string <uuid>
header Parameters
X-Cert-Client-subject
required
string
X-Cert-Client-issuer
required
string
X-Cert-Client-serialNumber
string
X-Cert-Client-decimalSerialNumber
integer <int32>
X-Cert-Client
required
string
Request Body schema: text/plain
required
string

Responses

1.1.0

Get secure key

This service retrieves a previously generated custom secure key

query Parameters
keyLabel
required
string
kekLabel
required
string

Responses

Generate secure key

This service returns a custom secure key

Request Body schema: application/json
required
algorithm
required
string
Value: "AES"
length
required
integer <int32> >= 1
keyLabel
string

Responses

Request samples

Content type
application/json
{
  • "algorithm": "AES",
  • "length": 1,
  • "keyLabel": "string"
}

Create CSR Instance Certificate

This service generates Instance Certificate based on CSR

Request Body schema: application/json
required
required
object (PublicKey)
required
object (InstanceCertificateConfiguration)

Responses

Request samples

Content type
application/json
{
  • "publicKey": {
    },
  • "certificateConfiguration": {
    }
}

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string",
  • "certificate": {
    }
}

Heartbeat

This service returns a heartbeat

Responses

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string"
}

Get secure random

This service returns a Secure Random byte array

query Parameters
length
integer <int32>
Default: 0

Responses

Generate secure key

This service generates SecureKeys

Request Body schema: application/json
required
algorithm
required
string
Value: "AES"
length
required
integer <int32> >= 1
keyLabel
string

Responses

Request samples

Content type
application/json
{
  • "algorithm": "AES",
  • "length": 1,
  • "keyLabel": "string"
}

Response samples

Content type
application/json
{
  • "secureKey": {
    }
}

Load balancer heartbeat

This service returns a load balancer heartbeat

Responses

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string"
}

Create Release Certificate

This service generates Release Certificate

Request Body schema: application/json
required
required
object (KekConfiguration)
required
object (ReleaseCertificateConfiguration)

Responses

Request samples

Content type
application/json
{
  • "kekConfiguration": {
    },
  • "certificateConfiguration": {
    }
}

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string",
  • "certificate": {
    },
  • "kek": {
    },
  • "privateKey": {
    }
}

Create Instance Certificate

This service generates Instance Certificate

Request Body schema: application/json
required
required
object (KekConfiguration)
required
object (InstanceCertificateConfiguration)

Responses

Request samples

Content type
application/json
{
  • "kekConfiguration": {
    },
  • "certificateConfiguration": {
    }
}

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string",
  • "certificate": {
    },
  • "wrappedPrivateKey": {
    },
  • "wrappedStorageKey": {
    }
}

1.2.0

Generate secure key

This service returns a custom secure key

Request Body schema: application/json
required
algorithm
required
string
Value: "AES"
length
required
integer <int32> >= 1
keyLabel
string

Responses

Request samples

Content type
application/json
{
  • "algorithm": "AES",
  • "length": 1,
  • "keyLabel": "string"
}

Create CSR Instance Certificate

This service generates Instance Certificate based on CSR

Request Body schema: application/json
required
required
object (PublicKey)
required
object (InstanceCertificateConfiguration)

Responses

Request samples

Content type
application/json
{
  • "publicKey": {
    },
  • "certificateConfiguration": {
    }
}

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string",
  • "certificate": {
    }
}

Heartbeat

This service returns a heartbeat

Responses

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string"
}

Get secure random

This service returns a Secure Random byte array

query Parameters
length
integer <int32>
Default: 0

Responses

Generate secure key

This service generates SecureKeys

Request Body schema: application/json
required
algorithm
required
string
Value: "AES"
length
required
integer <int32> >= 1
keyLabel
string

Responses

Request samples

Content type
application/json
{
  • "algorithm": "AES",
  • "length": 1,
  • "keyLabel": "string"
}

Response samples

Content type
application/json
{
  • "secureKey": {
    }
}

Load balancer heartbeat

This service returns a load balancer heartbeat

Responses

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string"
}

Create Release Certificate

This service generates Release Certificate

Request Body schema: application/json
required
required
object (KekConfiguration)
required
object (ReleaseCertificateConfiguration)

Responses

Request samples

Content type
application/json
{
  • "kekConfiguration": {
    },
  • "certificateConfiguration": {
    }
}

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string",
  • "certificate": {
    },
  • "kek": {
    },
  • "privateKey": {
    }
}

Create Instance Certificate

This service generates Instance Certificate

Request Body schema: application/json
required
required
object (KekConfiguration)
required
object (InstanceCertificateConfiguration)

Responses

Request samples

Content type
application/json
{
  • "kekConfiguration": {
    },
  • "certificateConfiguration": {
    }
}

Response samples

Content type
application/json
{
  • "resultCode": "string",
  • "resultMsg": "string",
  • "certificate": {
    },
  • "wrappedPrivateKey": {
    },
  • "wrappedStorageKey": {
    }
}