Device keys

Download OpenAPI specification:Download

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

Add device key

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.

SecurityOAuth2: ClientAccessToken
Request
path Parameters
user_id
required
string

ID of the user

Request Body schema: application/json
required
key_id
required
string

An identifier for the user's device

display_name
string

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

custom_data
object

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

public_key
required
string

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

Responses
201

Device key added

post/v1/users/{user_id}/device-keys
Request samples
application/json
{
  • "key_id": "string",
  • "display_name": "string",
  • "custom_data": { },
  • "public_key": "string"
}

Get all device keys

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

SecurityOAuth2: ClientAccessToken
Request
path Parameters
user_id
required
string

ID of the user

Responses
200
get/v1/users/{user_id}/device-keys
Request samples 
Response samples 
application/json
{
  • "result": [
    ]
}
Get device key
Retrieves a specific device key. For example, this can be used to verify that the device key exists and is active.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
ID of the user


 
key_id
required
string
An identifier for the user's device


 
Responses 
200
get/v1/users/{user_id}/device-keys/{key_id}
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Update device key
Updates the metadata of a device key, such as the friendly device name or other custom data.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
ID of the user


 
key_id
required
string
An identifier for the user's device


 
Request Body schema: application/json
required
display_name
string
Friendly device name, used when displaying a list of the user's devices


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


 
Responses 
200
Device key updated


put/v1/users/{user_id}/device-keys/{key_id}
Request samples 
application/json
{
  • "display_name": "string",
  • "custom_data": { }
}
Delete device key
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.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
ID of the user


 
key_id
required
string
An identifier for the user's device


 
Responses 
204
Device key deleted


delete/v1/users/{user_id}/device-keys/{key_id}
Request samples 
Validate device key
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.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
ID of the user


 
key_id
required
string
An identifier for the user's device


 
Request Body schema: application/json
required
challenge
required
string
Raw challenge before it was signed by the device


 
signature
required
string
Signed challenge


 
Responses 
200
post/v1/users/{user_id}/device-keys/{key_id}/validate
Request samples 
application/json
{
  • "challenge": "string",
  • "signature": "string"
}
Response samples 
application/json
{
  • "result": true
}
Block device key
Block a user's device. Once blocked, the device status will be Blocked and device validation will fail if requested.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
ID of the user


 
key_id
required
string
An identifier for the user's device


 
Responses 
200
Device blocked


put/v1/users/{user_id}/device-keys/{key_id}/block
Request samples 
Unblock device key
Unblocks a user's device. Once unblocked, the device status returns to Active and the device can be verified using the device key.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
ID of the user


 
key_id
required
string
An identifier for the user's device


 
Responses 
200
Device unblocked


put/v1/users/{user_id}/device-keys/{key_id}/unblock
Request samples