{
"openapi": "3.0.3",
"info": {
"title": "Devices",
"description": "This API exposes operations that allow applications to register and manage device entities in Mosaic. Use it to add new devices, list a user's devices, delete devices, and more.",
"version": ""
},
"servers": [
{
"url": "https://api.sbx.transmitsecurity.io/cis",
"description": "Sandbox environment"
},
{
"url": "https://api.transmitsecurity.io/cis",
"description": "US production environment"
},
{
"url": "https://api.eu.transmitsecurity.io/cis",
"description": "EU production environment"
},
{
"url": "https://api.ca.transmitsecurity.io/cis",
"description": "CA production environment"
},
{
"url": "https://api.au.transmitsecurity.io/cis",
"description": "AU production environment"
},
{
"url": "https://api.gasne1-ts01.transmitsecurity.io/cis",
"description": "JP production environment"
}
],
"security": [],
"paths": {
"/v1/users/{user_id}/devices": {
"post": {
"operationId": "createOrUpdateDevice",
"summary": "Create or update a device",
"description": "Registers a new device for the given user, or updates metadata of an existing one. This requires a **client access token** of the application, and must be called from the backend.
**Required permissions**: `apps:edit`, `[appId]:edit`, `devices:edit`.",
"parameters": [
{
"name": "user_id",
"required": true,
"in": "path",
"description": "User ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDeviceDto"
}
}
}
},
"responses": {
"200": {
"description": "Device created or updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceResponseDto"
}
}
}
}
},
"security": [
{
"ClientAccessToken": []
}
]
},
"get": {
"operationId": "getDevices",
"summary": "Get all devices for user",
"description": "Retrieves all devices registered for the given user. This requires a **client access token** of the application, and must be called from the backend.
**Required permissions**: `apps:read`, `[appId]:read`, `devices:read`.",
"parameters": [
{
"name": "user_id",
"required": true,
"in": "path",
"description": "User ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "List of devices",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DeviceResponseDto"
}
}
}
}
}
},
"security": [
{
"ClientAccessToken": []
}
]
}
},
"/v1/users/{user_id}/devices/{device_id}": {
"get": {
"operationId": "getDeviceById",
"summary": "Get device by ID",
"description": "Retrieves a specific device of the given user. This requires a **client access token** of the application, and must be called from the backend.
**Required permissions**: `apps:read`, `[appId]:read`, `devices:read`.",
"parameters": [
{
"name": "user_id",
"required": true,
"in": "path",
"description": "User ID",
"schema": {
"type": "string"
}
},
{
"name": "device_id",
"required": true,
"in": "path",
"description": "Device ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device info",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceResponseDto"
}
}
}
}
},
"security": [
{
"ClientAccessToken": []
}
]
},
"put": {
"operationId": "updateDevice",
"summary": "Update device",
"description": "Updates metadata fields of a specific device of the given user. This requires a **client access token** of the application, and must be called from the backend.
**Required permissions**: `apps:edit`, `[appId]:edit`, `devices:edit`.",
"parameters": [
{
"name": "user_id",
"required": true,
"in": "path",
"description": "User ID",
"schema": {
"type": "string"
}
},
{
"name": "device_id",
"required": true,
"in": "path",
"description": "Device ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDeviceDto"
}
}
}
},
"responses": {
"200": {
"description": "Device updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceResponseDto"
}
}
}
}
},
"security": [
{
"ClientAccessToken": []
}
]
},
"delete": {
"operationId": "deleteDevice",
"summary": "Delete device",
"description": "Deletes a specific device of the given user. This requires a **client access token** of the application, and must be called from the backend.
**Required permissions**: `apps:delete`, `[appId]:delete`, `devices:delete`.",
"parameters": [
{
"name": "user_id",
"required": true,
"in": "path",
"description": "User ID",
"schema": {
"type": "string"
}
},
{
"name": "device_id",
"required": true,
"in": "path",
"description": "Device ID",
"schema": {
"type": "string"
}
},
{
"name": "delete_bound_authenticators",
"required": false,
"in": "query",
"description": "Whether to also delete the authenticators bound to this device",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"204": {
"description": "Device deleted"
}
},
"security": [
{
"ClientAccessToken": []
}
]
}
},
"/v1/users/{user_id}/devices/{device_id}/suspend": {
"post": {
"operationId": "suspendUserDevice",
"summary": "Suspend device for user",
"description": "Suspends the specified device for the given user. This requires a **client access token** of the application, and must be called from the backend.
**Required permissions**: `apps:edit`, `[appId]:edit`, `devices:edit`.",
"parameters": [
{
"name": "user_id",
"required": true,
"in": "path",
"description": "User ID",
"schema": {
"type": "string"
}
},
{
"name": "device_id",
"required": true,
"in": "path",
"description": "Device ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device suspended"
}
},
"security": [
{
"ClientAccessToken": []
}
]
}
},
"/v1/users/{user_id}/devices/{device_id}/reactivate": {
"post": {
"operationId": "reactivateUserDevice",
"summary": "Reactivate device for user",
"description": "Reactivates the specified device for the given user. This requires a **client access token** of the application, and must be called from the backend.
**Required permissions**: `apps:edit`, `[appId]:edit`, `devices:edit`.",
"parameters": [
{
"name": "user_id",
"required": true,
"in": "path",
"description": "User ID",
"schema": {
"type": "string"
}
},
{
"name": "device_id",
"required": true,
"in": "path",
"description": "Device ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Device reactivated"
}
},
"security": [
{
"ClientAccessToken": []
}
]
}
},
"/v1/devices": {
"get": {
"operationId": "filterDevices",
"summary": "Filter devices",
"description": "Filters and lists devices within the application. This requires a **client access token** of the application, and must be called from the backend.
**Required permissions**: `apps:read`, `[appId]:read`, `devices:read`.",
"parameters": [
{
"name": "device_id",
"required": false,
"in": "query",
"description": "Filter by device ID",
"schema": {
"type": "string"
}
},
{
"name": "user_id",
"required": false,
"in": "query",
"description": "Filter by user ID",
"schema": {
"type": "string"
}
},
{
"name": "status",
"required": false,
"in": "query",
"description": "Filter by device status",
"schema": {
"enum": [
"active",
"suspended"
],
"type": "string"
}
},
{
"name": "device_type",
"required": false,
"in": "query",
"description": "Filter by device type",
"schema": {
"enum": [
"mobile",
"web"
],
"type": "string"
}
},
{
"name": "last_auth_attempt",
"required": false,
"in": "query",
"description": "Filter devices with last auth attempt at or after this date",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"name": "last_authenticated",
"required": false,
"in": "query",
"description": "Filter devices with last authenticated at or after this date",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"name": "order_by",
"required": false,
"in": "query",
"description": "Field to order by",
"schema": {
"default": "created_at",
"enum": [
"device_status",
"created_at"
],
"type": "string"
}
},
{
"name": "order",
"required": false,
"in": "query",
"description": "Sort direction",
"schema": {
"default": "desc",
"enum": [
"asc",
"desc"
],
"type": "string"
}
},
{
"name": "page_offset",
"required": false,
"in": "query",
"description": "Number of records to skip",
"schema": {
"default": 0,
"type": "number"
}
},
{
"name": "page_size",
"required": false,
"in": "query",
"description": "Number of records to return (1–100)",
"schema": {
"minimum": 1,
"maximum": 100,
"default": 100,
"type": "number"
}
}
],
"responses": {
"200": {
"description": "Filtered list of devices",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceListResponseDto"
}
}
}
}
},
"security": [
{
"ClientAccessToken": []
}
]
}
}
},
"components": {
"schemas": {
"CreateDeviceDto": {
"type": "object",
"properties": {
"device_id": {
"type": "string",
"description": "Unique identifier for the device"
},
"display_name": {
"type": "string",
"description": "Display name for the device"
},
"device_type": {
"type": "string",
"enum": [
"mobile",
"web"
],
"description": "Type of the device"
},
"hardware_model": {
"type": "string",
"description": "Hardware model of the device"
},
"os": {
"type": "string",
"description": "Operating system of the device"
},
"browser": {
"type": "string",
"description": "Browser used on the device"
},
"registered_region": {
"type": "string",
"description": "Region from which the device was registered"
}
},
"required": [
"device_id",
"device_type"
]
},
"DeviceResponseDto": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "User identifier"
},
"device_id": {
"type": "string",
"description": "Unique identifier for the device"
},
"status": {
"type": "string",
"enum": [
"active",
"suspended"
],
"description": "Status of the device"
},
"display_name": {
"type": "string",
"description": "Display name for the device"
},
"device_type": {
"type": "string",
"enum": [
"mobile",
"web"
],
"description": "Type of the device"
},
"hardware_model": {
"type": "string",
"description": "Hardware model of the device"
},
"os": {
"type": "string",
"description": "Operating system of the device"
},
"browser": {
"type": "string",
"description": "Browser used on the device"
},
"registered_ip": {
"type": "string",
"description": "IP address from which the device was registered"
},
"registered_region": {
"type": "string",
"description": "Region from which the device was registered"
},
"last_authenticated": {
"format": "date-time",
"type": "string",
"description": "Timestamp of last successful authentication"
},
"last_auth_attempt": {
"format": "date-time",
"type": "string",
"description": "Timestamp of last authentication attempt"
},
"created_at": {
"format": "date-time",
"type": "string",
"description": "Timestamp when the device was created"
},
"updated_at": {
"type": "string",
"description": "Timestamp when the device was last updated",
"format": "date-time"
}
},
"required": [
"user_id",
"device_id",
"status",
"device_type",
"created_at"
]
},
"UpdateDeviceDto": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"description": "Display name for the device"
},
"hardware_model": {
"type": "string",
"description": "Hardware model of the device"
},
"os": {
"type": "string",
"description": "Operating system of the device"
},
"browser": {
"type": "string",
"description": "Browser used on the device"
}
}
},
"DeviceListResponseDto": {
"type": "object",
"properties": {
"result": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DeviceResponseDto"
}
},
"total_count": {
"type": "number",
"description": "Total number of matching devices"
}
},
"required": [
"result",
"total_count"
]
}
},
"securitySchemes": {
"bearer": {
"scheme": "bearer",
"bearerFormat": "JWT",
"type": "http"
},
"UserAccessToken": {
"type": "http",
"description": "A token returned upon end-user authentication, which provides access to resources and data for the user and app for which it was generated",
"scheme": "bearer",
"bearerFormat": "JWT"
},
"AdminAccessToken": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "/oidc/token",
"scopes": {}
}
},
"description": "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"
},
"ClientAccessToken": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "/oidc/token",
"scopes": {}
}
},
"description": "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)"
},
"OrgAdminAccessToken": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "/oidc/token",
"scopes": {}
}
},
"description": "A token returned upon B2B authentication for a user that has the organizationAdmin or organizationCreator role."
}
}
}
}