# 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. <br><br> 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).<br><br>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.<br><br>**Note: This feature requires the client to implement the relevant cryptography APIs exposed by the browser or mobile platform (Android or iOS).**


## 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
```

## Security

### bearer

Type: http
Scheme: bearer
Bearer Format: JWT

### UserAccessToken

A token returned upon end-user authentication, which provides access to resources and data for the user and app for which it was generated

Type: http
Scheme: bearer
Bearer Format: JWT

### AdminAccessToken

A token generated by a management application using the [token endpoint](/openapi/token.openapi/other/getaccesstoken). It provides access to all resources for the tenant and its apps

Type: oauth2

### ClientAccessToken

A token generated by an end-user application using the [token endpoint](/openapi/token.openapi/other/getaccesstoken). It provides access to resources and data on the tenant level or associated with the specific application (but not other apps in the tenant)

Type: oauth2

### OrgAdminAccessToken

A token returned upon B2B authentication for a user that has the organizationAdmin or organizationCreator role.

Type: oauth2

## Download OpenAPI description

[Device keys](https://developer.transmitsecurity.com/_bundle/openapi/user/device-key.openapi.yaml)

## Other

### Add device key

 - [POST /v1/users/{user_id}/device-keys](https://developer.transmitsecurity.com/openapi/user/device-key.openapi/other/createdevicekeys.md): 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.

### Get all device keys

 - [GET /v1/users/{user_id}/device-keys](https://developer.transmitsecurity.com/openapi/user/device-key.openapi/other/getdevicekeysforuser.md): 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.

### Get device key

 - [GET /v1/users/{user_id}/device-keys/{key_id}](https://developer.transmitsecurity.com/openapi/user/device-key.openapi/other/getdevicekeys.md): 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.

### Update device key

 - [PUT /v1/users/{user_id}/device-keys/{key_id}](https://developer.transmitsecurity.com/openapi/user/device-key.openapi/other/updatedevicekey.md): 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.

### Delete device key

 - [DELETE /v1/users/{user_id}/device-keys/{key_id}](https://developer.transmitsecurity.com/openapi/user/device-key.openapi/other/deletedevicekeys.md): 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.

### Validate device key

 - [POST /v1/users/{user_id}/device-keys/{key_id}/validate](https://developer.transmitsecurity.com/openapi/user/device-key.openapi/other/validatedevicekeys.md): 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.

### Block device key

 - [PUT /v1/users/{user_id}/device-keys/{key_id}/block](https://developer.transmitsecurity.com/openapi/user/device-key.openapi/other/blockdevicekey.md): 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.

### Unblock device key

 - [PUT /v1/users/{user_id}/device-keys/{key_id}/unblock](https://developer.transmitsecurity.com/openapi/user/device-key.openapi/other/unblockdevicekey.md): 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.