Skip to content

Device keys

Device keys are used to cryptographically bind devices to a user for strong device identification. This allows the device to act as a user-identifying factor, and allows elevating trust for known devices.

These APIs are used to manage and verify bound devices for a user and application. The device may correspond to either a browser (for web apps) or a mobile device (for mobile apps).

Device binding relies on a cryptographic key-pair generated by the device. The private key is securely stored on the device (typically protected by biometrics or a PIN), while the public key is stored by Transmit for a given user. When needed, the device uses the private key to sign a challenge that Transmit verifies using the public key.

Note: This feature requires the client to implement the relevant cryptography APIs exposed by the browser or mobile platform (Android or iOS).

Download OpenAPI description
device-key.openapi.json
device-key.openapi.yaml
Languages
Servers
Sandbox environment
https://api.sbx.transmitsecurity.io/cis/
Production environment (US)
https://api.transmitsecurity.io/cis/
Production environment (EU)
https://api.eu.transmitsecurity.io/cis/
Production environment (CA)
https://api.ca.transmitsecurity.io/cis/
Production environment (AU)
https://api.au.transmitsecurity.io/cis/

Add device key

Request

Registers a device key in the platform for a specific user and app. Device keys are generated by the client using the relevant cryptography APIs exposed by the browser or mobile platform (Android or iOS). Once registered, the device key cryptographically binds the device to the given user for secure device identification.

Note: The key should be generated using the RSA-PSS algorithm and SHA-256 hash.

Required permissions: apps:create, [appId]:create, devices:create.

Security
ClientAccessToken
Path
user_idstringrequired

ID of the user

Bodyapplication/jsonrequired
key_idstringrequired

An identifier for the user's device

display_namestring

Friendly device name, used when displaying a list of the user's devices

custom_dataobject

Custom data stored for this device, such as tags or device data obtained using other tools

push_configobject
public_keystringrequired

Device public key as a base-64 string. This corresponds to the cryptographic key-pair generated by the client

curl -i -X POST \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{user_id}/device-keys' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "key_id": "string",
    "display_name": "string",
    "custom_data": {},
    "push_config": {
      "device_token": "stringstringstringstringstringst",
      "type": "FCM",
      "bundle_id": "string"
    },
    "public_key": "string"
  }'

Responses

Device key added

Get all device keys

Request

Retrieves all the device keys registered for a specific user. This can be used to display a list of the user's devices.

Required permissions: apps:read, [appId]:read, devices:read, apps:list, [appId]:list, devices:list.

Security
ClientAccessToken
Path
user_idstringrequired

ID of the user

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{user_id}/device-keys' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json
resultArray of objectsrequired
result[].​statusstringrequired
Enum"Active""Blocked""Suspended"
result[].​display_namestring

Friendly device name, used when displaying a list of the user's devices

result[].​custom_dataobject

Custom data stored for this device, such as tags or device data obtained using other tools

result[].​push_configobject
result[].​key_idstring

Identifier of the user's device

result[].​created_atstring(date-time)required

Date the device key was added

result[].​updated_atstring(date-time)required

Date the device key metadata was last updated

Response
application/json
{
  "result": [
    { … }
  ]
}

Get device key

Request

Retrieves a specific device key. For example, this can be used to verify that the device key exists and is active.

Required permissions: apps:read, [appId]:read, devices:read.

Security
ClientAccessToken
Path
user_idstringrequired

ID of the user

key_idstringrequired

An identifier for the user's device

curl -i -X GET \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{user_id}/device-keys/{key_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json
resultobjectrequired
result.​statusstringrequired
Enum"Active""Blocked""Suspended"
result.​display_namestring

Friendly device name, used when displaying a list of the user's devices

result.​custom_dataobject

Custom data stored for this device, such as tags or device data obtained using other tools

result.​push_configobject
result.​key_idstring

Identifier of the user's device

result.​created_atstring(date-time)required

Date the device key was added

result.​updated_atstring(date-time)required

Date the device key metadata was last updated

Response
application/json
{
  "result": {
    "status": "Active",
    "display_name": "string",
    "custom_data": {},
    "push_config": { … },
    "key_id": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

Update device key

Request

Updates the metadata of a device key, such as the friendly device name or other custom data.

Required permissions: apps:edit, [appId]:edit, devices:edit.

Security
ClientAccessToken
Path
user_idstringrequired

ID of the user

key_idstringrequired

An identifier for the user's device

Bodyapplication/jsonrequired
display_namestring

Friendly device name, used when displaying a list of the user's devices

custom_dataobject

Custom data stored for this device, such as tags or device data obtained using other tools

push_configobject
curl -i -X PUT \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{user_id}/device-keys/{key_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "display_name": "string",
    "custom_data": {},
    "push_config": {
      "device_token": "stringstringstringstringstringst",
      "type": "FCM",
      "bundle_id": "string"
    }
  }'

Responses

Device key updated

Delete device key

Request

Unregisters the user's device. For example, it can be used in case the device is lost, stolen, or no longer in the user's possession.

Required permissions: apps:delete, [appId]:delete, devices:delete.

Security
ClientAccessToken
Path
user_idstringrequired

ID of the user

key_idstringrequired

An identifier for the user's device

curl -i -X DELETE \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{user_id}/device-keys/{key_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Device key deleted

Validate device key

Request

Verifies that the user's device is in their possession. Before calling this API, the device signs a challenge using the private key stored by the device. This API is used to verify the signed challenge using the device public key. In case the device is blocked, this validation will fail.

Note: The challenge should be generated by your client backend..

Required permissions: apps:execute, [appId]:execute, devices:execute.

Security
ClientAccessToken
Path
user_idstringrequired

ID of the user

key_idstringrequired

An identifier for the user's device

Bodyapplication/jsonrequired
challengestringrequired

Raw challenge before it was signed by the device

signaturestringrequired

Signed challenge

curl -i -X POST \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{user_id}/device-keys/{key_id}/validate' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "challenge": "string",
    "signature": "string"
  }'

Responses

Bodyapplication/json
resultbooleanread-onlyrequired

Boolean value indicating if device key validation succeeded

Response
application/json
{
  "result": true
}

Block device key

Request

Block a user's device. Once blocked, the device status will be Blocked and device validation will fail if requested.

Required permissions: apps:edit, [appId]:edit, devices:edit.

Security
ClientAccessToken
Path
user_idstringrequired

ID of the user

key_idstringrequired

An identifier for the user's device

curl -i -X PUT \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{user_id}/device-keys/{key_id}/block' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Device blocked

Unblock device key

Request

Unblocks a user's device. Once unblocked, the device status returns to Active and the device can be verified using the device key.

Required permissions: apps:edit, [appId]:edit, devices:edit.

Security
ClientAccessToken
Path
user_idstringrequired

ID of the user

key_idstringrequired

An identifier for the user's device

curl -i -X PUT \
  'https://api.sbx.transmitsecurity.io/cis/v1/users/{user_id}/device-keys/{key_id}/unblock' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Device unblocked