# Device Management APIs

This page contains detail about the Device Provider Management API's.

* [Device Providers](#device-providers)
* [Foundational Trust Providers](#foundational-trust-providers)
* [Devices](#devices)
* [MDS API](#mds-api)

## Device Providers

* [POST /deviceprovider](#post-deviceprovider-private)
* [PUT /deviceprovider](#put-deviceprovider)

### POST /deviceprovider (Private)

This service creates a device service provider in the device provider table as well as a record in the device provider history table.

#### Resource URL

`POST https://{base_url}/v1/masterdata/deviceprovider`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Parameters

| Name             | Required | Description                                                | Default Value | Example |
| ---------------- | -------- | ---------------------------------------------------------- | ------------- | ------- |
| vendorName       | Yes      | This is the name of the vendor                             | NA            | NA      |
| address          | Yes      | This is the address of the vendor                          | NA            | NA      |
| email            | Yes      | This is the email of the vendor                            | NA            | NA      |
| contactNumber    | Yes      | This is the contact number of the vendor                   | NA            | NA      |
| certificateAlias | Yes      | This is the certificate alias of the vendor                | NA            | NA      |
| isActive         | Yes      | This field represents whether this entity is active or not | NA            | NA      |

#### Request

```
{
  "id": "io.mosip.masterdata.deviceprovider.create",
  "metadata": {},
  "request": {
	"address": "Address of Test Vendor",
	"certificateAlias": "Test",
	"contactNumber": "9663175928",
	"email": "test@mosip.io",
	"isActive": true,
	"vendorName": "Test Vendor"
  },
  "requesttime": "2020-02-06T09:13:59.522Z",
  "version": "1.0"
}
```

#### Response

**Success response**

```
{
  "id": "io.mosip.masterdata.deviceprovider.create",
  "version": "1.0",
  "responsetime": "2020-02-06T09:13:59.522Z",
  "metadata": null,
  "response": {
	"id": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
	"vendorName": "Test Vendor",
	"address": "Address of Test Vendor",
	"email": "test@mosip.io",
	"contactNumber": "9663175928",
	"certificateAlias": "Test",
	"isActive": true,
	"createdBy": "110006",
	"updatedBy": null,
	"isDeleted": null
  },
  "errors": []
}
```

**Response code: 200**

**Failure response**

```
{
  "id": "io.mosip.masterdata.deviceprovider.create",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-06T09:13:59.522Z", 
  "errors": [{
	"errorCode": "KER-ATH-401",
	"message": "Authentication Failed"
  }],
  "response": null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                                      | Error Description                                                  |
| ----------- | -------------------------------------------------- | ------------------------------------------------------------------ |
| KER-ATH-401 | Authentication Failed                              | If no role/invalid token is detected                               |
| ADM-DPM-010 | Mandatory input parameter is missing               | If any mandatory input parameter is missing                        |
| ADM-DPM-011 | Device Provider already exist                      | If the Device provider details already exist                       |
| ADM-DPM-012 | Error occurred while registering a Device Provider | If there an error from DB while storing details of Device Provider |

### PUT /deviceprovider

This service updates a device service provider in the device provider table as well as creates a record in the device provider history table.

#### Resource URL

`PUT https://{base_url}/v1/masterdata/deviceprovider`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Parameters

| Name             | Required | Description                                                      | Default Value | Example |
| ---------------- | -------- | ---------------------------------------------------------------- | ------------- | ------- |
| vendorName       | Yes      | This is the name of the vendor                                   | NA            | NA      |
| address          | Yes      | This is the address of the vendor                                | NA            | NA      |
| email            | Yes      | This is the email of the vendor                                  | NA            | NA      |
| contactNumber    | Yes      | This is the contact number of the vendor                         | NA            | NA      |
| certificateAlias | Yes      | This is the certificate alias of the vendor                      | NA            | NA      |
| isActive         | Yes      | This field represents whether this entity is active or not       | NA            | NA      |
| id               | Yes      | This is the unique id of the vendor which was generated by MOSIP | NA            | NA      |

#### Request

```
{
  "id": "io.mosip.masterdata.deviceprovider.update",
  "metadata": {},
  "request": {
    "address": "New Address of Test Vendor",
    "certificateAlias": "changed",
    "contactNumber": "9000000000",
    "email": "test@mosip.io",
    "id": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
    "isActive": true,
    "vendorName": "Test Vendor"
  },
  "requesttime": "2020-02-10T09:13:59.522Z",
  "version": "1.0"
}
```

#### Response

**Success response**

```
{
  "id": "io.mosip.masterdata.deviceprovider.update",
  "version": "1.0",
  "responsetime": "2020-02-10T09:13:59.522Z",
  "metadata": null,
  "response": {
    "id": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
    "vendorName": "Test Vendor",
    "address": "New Address of Test Vendor",
    "email": "test@mosip.io",
    "contactNumber": "9000000000",
    "certificateAlias": "changed",
    "isActive": true,
    "createdBy": "110006",
    "updatedBy": "110005",
    "isDeleted": null,
  },
  "errors": []
}
```

**Response code: 200**

**Failure response**

```
{
  "id": "io.mosip.masterdata.deviceprovider.update",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-10T09:13:59.522Z",
  "errors": [{
	"errorCode": "KER-ATH-401",
	"message": "Authentication Failed"
  }],
  "response" : null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                                      | Error Description                                                  |
| ----------- | -------------------------------------------------- | ------------------------------------------------------------------ |
| KER-ATH-401 | Authentication Failed                              | If no role/invalid token is detected                               |
| ADM-DPM-013 | Mandatory input parameter is missing               | If any mandatory input parameter is missing                        |
| ADM-DPM-014 | Error occurred while registering a Device Provider | If there an error from DB while storing details of Device Provider |

## Foundational Trust Providers

* [POST /foundationaltrustprovider](#post-foundationaltrustprovider)
* [PUT /foundationaltrustprovider](#put-foundationaltrustprovider)

### POST /foundationaltrustprovider

This service creates a foundational trust provider.

#### Resource URL

`POST https://{base_url}/v1/masterdata/foundationaltrustprovider`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Parameters

| Name      | Required | Description                                                | Default Value | Example |
| --------- | -------- | ---------------------------------------------------------- | ------------- | ------- |
| name      | Yes      | This is the name of the vendor                             | NA            | NA      |
| address   | Yes      | This is the address of the vendor                          | NA            | NA      |
| email     | Yes      | This is the email of the vendor                            | NA            | NA      |
| contactNo | Yes      | This is the contact number of the vendor                   | NA            | NA      |
| isActive  | Yes      | This field represents whether this entity is active or not | NA            | NA      |
| certAlias | Yes      | This is the certificate alias of the vendor                | NA            | NA      |

#### Request

```
{
  "id": "io.mosip.masterdata.foundationaltrustprovider.create",
  "metadata": {},
  "request": {
    "name": "FTP 1",
    "address": "Address of FTP 1",
    "email": "FTP1@mosip.io",
    "contactNo": "9876543210",
    "certAlias": "Test",
    "isActive": true
  },
  "requesttime": "2020-02-06T09:13:59.522Z",
  "version": "1.0"
}
```

#### Response

**Success response**

```
{
  "id": "io.mosip.masterdata.foundationaltrustprovider.create",
  "version": "1.0",
  "responsetime": "2020-02-06T09:13:59.522Z",
  "metadata": null,
  "response": {
    "id": "83cdb6ea-6e62-11ea-bc55-0242ac130003",
    "name": "FTP 1",
    "address": "Address of FTP 1",
    "email": "FTP1@mosip.io",
    "contactNo": "9876543210",
    "certAlias": "Test",
    "isActive": true,
    "createdBy": "110006",
    "createdDateTime": "2020-02-06T09:13:59.522Z",
    "updatedBy": null,
    "updatedDateTime": null,
    "isDeleted": null,
    "deletedDateTime": null
  },
  "errors": null
}
```

**Response code: 200**

**Failure response**

```
{
  "id": "io.mosip.masterdata.foundationaltrustprovider.create",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-06T09:13:59.522Z",
  "errors": [{
	"errorCode": "KER-ATH-401",
	"message": "Authentication Failed"
  }],
  "response": null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                                                  | Error Description                                                              |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| KER-ATH-401 | Authentication Failed                                          | If no role/invalid token is detected                                           |
| ADM-DPM-015 | Mandatory input parameter is missing                           | If any mandatory input parameter is missing                                    |
| ADM-DPM-016 | Foundational Trust Provider already exist                      | If the Foundational Trust provider details already exist                       |
| ADM-DPM-017 | Error occurred while registering a Foundational Trust Provider | If there an error from DB while storing details of Foundational Trust Provider |

### PUT /foundationaltrustprovider

This service updates a foundational trust provider in the foundational trust provider table as well as creates a record in the foundational trust provider history table.

#### Resource URL

`PUT https://{base_url}/v1/masterdata/foundationaltrustprovider`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Parameters

| Name      | Required | Description                                                                  | Default Value | Example |
| --------- | -------- | ---------------------------------------------------------------------------- | ------------- | ------- |
| name      | Yes      | This is the name of the vendor                                               | NA            | NA      |
| address   | yes      | This is the address of the vendor                                            | NA            | NA      |
| email     | Yes      | This is the email of the vendor                                              | NA            | NA      |
| contactNo | Yes      | This is the contact number of the vendor                                     | NA            | NA      |
| isactive  | Yes      | This field represents whether this entity is active or not                   | NA            | NA      |
| id        | Yes      | This is the Unique ID that was generated for the foundational trust provider | NA            | NA      |

#### Request

```
{
  "id": "io.mosip.masterdata.foundationaltrustprovider.update",
  "metadata": {},
  "request": {
    "active": true,
    "id": "83cdb6ea-6e62-11ea-bc55-0242ac130003",
    "name": "FTP 1",
    "address": "Address of FTP 1",
    "email": "FTP1test@mosip.io",
    "contactNo": "9876543210",
    "certAlias": "Change",
    "isActive": true
  },
  "requesttime": "2020-02-10T09:13:59.522Z",
  "version": "1.0"
}
```

#### Response

**Success response**

```
{
  "id": "io.mosip.masterdata.foundationaltrustprovider.update",
  "version": "1.0",
  "responsetime": "2020-02-10T09:13:59.522Z",
  "metadata": null,
  "response": {
    "id": "83cdb6ea-6e62-11ea-bc55-0242ac130003",
    "name": "FTP 1",
    "address": "Address of FTP 1",
    "email": "FTP1test@mosip.io",
    "contactNo": "9876543210",
    "certAlias": "Change",
    "isActive": true,
    "createdBy": "110006",
    "createdDateTime": "2020-02-06T09:13:59.522Z",
    "updatedBy": "110005",
    "updatedDateTime": "2020-02-10T09:13:59.522Z",
    "isDeleted": null,
    "deletedDateTime": null
  },
  "errors": null
}
```

**Response code: 200**

**Failure response**

```
{
  "id": "io.mosip.masterdata.foundationaltrustprovider.update",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-10T09:13:59.522Z",
  "errors": [{
	"errorCode": "KER-ATH-401",
	"message": "Authentication Failed"
  }],
  "response": null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                                                  | Error Description                                                              |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| KER-ATH-401 | Authentication Failed                                          | If no role/invalid token is detected                                           |
| ADM-DPM-018 | Mandatory input parameter is missing                           | If any mandatory input parameter is missing                                    |
| ADM-DPM-019 | Error occurred while registering a Foundational Trust Provider | If there an error from DB while storing details of Foundational Trust Provider |

***

## Devices

* [POST /registereddevices](#post-registereddevices)
* [DELETE /deregister/{deviceCode}](#delete-deregister-deviceCode)
* [PUT /registereddevices/status](#put-registereddevices-status)
* [POST/deviceprovidermanagement/validate](#post-deviceprovidermanagement-validate)

### POST /registereddevices

This service registers a device in MOSIP as well as creates a history record.

#### Resource URL

`POST https://{base_url}/v1/masterdata/registereddevices`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

***Note:*** Device data contains the device details in Base64 encoded format.

#### Request

**Parameters for device registration API**

| Name       | Required | Description                             | Default Value | Example |
| ---------- | -------- | --------------------------------------- | ------------- | ------- |
| deviceData | Yes      | This contains the encrypted device data | NA            | NA      |

**Request for device registration API\*\***

```
{
  "id": "io.mosip.masterdata.device.create",
  "metadata": {},
  "request": {
    "deviceData": "eyJkZXZpY2VJZCI6IjcwOTU5ZGQ1LWU0NWYtNDM4YS05ZmY4LTliMjYzOTA4ZTU3MiIsInB1cnBvc2UiOiJBVVRIIiwiZGV2aWNlSW5mbyI6eyJkZXZpY2VTdWJJZCI6IjEiLCJjZXJ0aWZpY2F0aW9uIjoiTDAiLCJkaWdpdGFsSWQiOiJleUp6WlhKcFlXeE9ieUk2SWpFNE1ERXhOakE1T1RJaUxDSmtaWFpwWTJWUWNtOTJhV1JsY2lJNklsTlpUa05DV1ZSRklpd2laR1YyYVdObFVISnZkbWxrWlhKSlpDSTZJbE5aVGtOQ1dWUkZMazFETURGQklpd2liV0ZyWlNJNklrMURNREZCSWl3aWJXOWtaV3dpT2lKVFRVbEVRMHdpTENKa1lYUmxWR2x0WlNJNklqSXdNakF0TURFdE1UTlVNRGM2TWpBNk5ESXVNVGsxV2lJc0luUjVjR1VpT2lKR2FXNW5aWEp3Y21sdWRDSXNJbk4xWWxSNWNHVWlPaUpUYVc1bmJHVWlmUT09IiwiZmlybXdhcmUiOiJmaXJtd2FyZSIsImRldmljZUV4cGlyeSI6IjIwMjAtMDEtMTNUMTI6NTA6NDIuMTk2WiIsInRpbWVTdGFtcCI6IjIwMjAtMDEtMTNUMTI6NTA6NDIuMjA4WiJ9LCJmb3VuZGF0aW9uYWxUcnVzdFByb3ZpZGVySWQiOiIifQ=="
  },
  "requesttime": "2020-02-16T09:13:59.522Z",
  "version": "v1"
}
```

***Note:*** Device data contains the device id, purpose, device info, and foundational trust provider id

**Device Data**

**Parameters for device data**

| Name                        | Required | Description                                       | Default Value | Example              |
| --------------------------- | -------- | ------------------------------------------------- | ------------- | -------------------- |
| deviceId                    | Yes      | This is the ID of the device                      | NA            | NA                   |
| foundationalTrustProviderId | No       | This is the ID of the foundational trust provider | NA            | NA                   |
| purpose                     | Yes      | This is the purpose of the device                 | NA            | AUTH or REGISTRATION |

If purpose is AUTH , we will auto-generate the code. If purpose is REGISTRATION, device ID will be populated as device code.

**Decoded JSON for device data**

```
{
  "deviceId": "70959dd5-e45f-438a-9ff8-9b263908e572",
  "purpose": "AUTH",
  "deviceInfo": {
    "deviceSubId": "1",
    "certification": "L0",
    "digitalId": "eyJzZXJpYWxObyI6IjE4MDExNjA5OTIiLCJkZXZpY2VQcm92aWRlciI6IlNZTkNCWVRFIiwiZGV2aWNlUHJvdmlkZXJJZCI6IlNZTkNCWVRFLk1DMDFBIiwibWFrZSI6Ik1DMDFBIiwibW9kZWwiOiJTTUlEQ0wiLCJkYXRlVGltZSI6IjIwMjAtMDEtMTNUMDc6MjA6NDIuMTk1WiIsInR5cGUiOiJGaW5nZXJwcmludCIsInN1YlR5cGUiOiJTaW5nbGUifQ==",
    "firmware": "firmware",
    "deviceExpiry": "2021-02-16T12:50:42.196Z",
    "timeStamp": "2020-02-16T12:50:42.208Z"
  },
  "foundationalTrustProviderId": "83cdb6ea-6e62-11ea-bc55-0242ac130003"
}
```

**Device Info**

**Parameters for device info**

| Name          | Required | Description                                               | Default Value     | Example  |
| ------------- | -------- | --------------------------------------------------------- | ----------------- | -------- |
| certification | Yes      | This is the certification level of the device             | NA                | L1 or L0 |
| deviceSubId   | Yes      | This is the sub type id of the device                     | NA                | 1,2,3    |
| firmware      | Yes      | This is the firmware of the device                        | NA                | NA       |
| timeStamp     | Yes      | This is the current timestamp when the request is created | NA                | NA       |
| deviceExpiry  | No       | This is the expiry date of the device                     | current timestamp | NA       |
| digitalID     | Yes      | This is the encoded digital ID of the device              | NA                | NA       |

**Device Info extracted from decode device data JSON**

```
"deviceInfo": {
  "deviceSubId": "1",
  "certification": "L0",
  "digitalId": "eyJzZXJpYWxObyI6IjE4MDExNjA5OTIiLCJkZXZpY2VQcm92aWRlciI6IlNZTkNCWVRFIiwiZGV2aWNlUHJvdmlkZXJJZCI6IlNZTkNCWVRFLk1DMDFBIiwibWFrZSI6Ik1DMDFBIiwibW9kZWwiOiJTTUlEQ0wiLCJkYXRlVGltZSI6IjIwMjAtMDEtMTNUMDc6MjA6NDIuMTk1WiIsInR5cGUiOiJGaW5nZXJwcmludCIsInN1YlR5cGUiOiJTaW5nbGUifQ==",
  "firmware": "firmware",
  "deviceExpiry": "2021-02-16T12:50:42.196Z",
  "timeStamp": "2020-02-16T12:50:42.208Z"
}
```

**Digital ID**

Digital Id will be encoded.

**Parameters for digital ID**

| Name             | Required | Description                                                  | Default Value | Example |
| ---------------- | -------- | ------------------------------------------------------------ | ------------- | ------- |
| deviceProvider   | Yes      | This is the name of the device provider                      | NA            | NA      |
| deviceProviderId | Yes      | This is the id of the device provider                        | NA            | NA      |
| type             | Yes      | This is the type of the device                               | NA            | NA      |
| subtype          | Yes      | This is the sub type of the device                           | NA            | NA      |
| serialNo         | Yes      | This is the serial number of the device                      | NA            | NA      |
| make             | Yes      | This is the make of the device                               | NA            | NA      |
| model            | Yes      | This is the model of the device                              | NA            | NA      |
| dateTime         | Yes      | This is the current date time when the digital ID is created | NA            | NA      |

**Decoded JSON for digital ID**

```
{
  "serialNo": "1801160992",
  "deviceProvider": "Test Vendor",
  "deviceProviderId": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
  "make": "MC01A",
  "model": "TVSFD",
  "dateTime": "2020-02-16T07:20:42.195Z",
  "type": "Fingerprint",
  "deviceSubType": "Single"
}
```

#### Response

**Success Response**

```
{
  "id": "io.mosip.masterdata.device.create",
  "version": "1.0",
  "responsetime": "2020-01-13T07:25:29.764Z",
  "metadata": null,
  "response": "eyJhbGciOiJSUzI1NiIsInR5cGUiOiJKV1MifQ==.eyJzdGF0dXMiOiJSRUdJU1RFUkVEIiwiZGlnaXRhbElkIjoiZXlKelpYSnBZV3hPYnlJNklqRTRNREV4TmpBNU9USWlMQ0prWlhacFkyVlFjbTkyYVdSbGNpSTZJbE5aVGtOQ1dWUkZJaXdpWkdWMmFXTmxVSEp2ZG1sa1pYSkpaQ0k2SWxOWlRrTkNXVlJGTGsxRE1ERkJJaXdpYldGclpTSTZJazFETURGQklpd2liVzlrWld3aU9pSlRUVWxFUTB3aUxDSmtZWFJsVkdsdFpTSTZJakl3TWpBdE1ERXRNVE5VTURjNk1qQTZOREl1TVRrMVdpSXNJblI1Y0dVaU9pSkdhVzVuWlhKd2NtbHVkQ0lzSW5OMVlsUjVjR1VpT2lKVGFXNW5iR1VpZlEiLCJkZXZpY2VDb2RlIjoiOGNkNDI4NjQtMmNkYy00MDY3LThkMTEtNDBiMjVmZjhjNzYwIiwiZW52IjoibG9jYWwiLCJ0aW1lU3RhbXAiOiIyMDIwLTAxLTEzVDEyOjU1OjI5LjkxOFoifQ==.dkd3Mlo2TStDT2JpM1lHY2Q1OFNJRkJ6T0E5bFZ6dUFlZnN3NHhQZzEzWE42LzAvWVZ6Qm0yNnpmZXFPRXdmWHNKQUN4aC9QNExuM2RHcjhSR2diZjEvRXgwNktCOEhhbEM1VjhPMFh4VGxmK3ZSZFlJeTZhbFh0cS8rY0s0VjRSYUpHYjVDL2kweHdzMFF3bHh0UEo4cFIvbnVrb1d5dzNNTmRDSkNZaVlGSkxVUUpKbnhyaEtYR3dvM1ZlcVNkaEYrMStjS1ZpSzFWSlQ5OHFsMjFhTUp0MGd4Wko1Rzg5V0lSbi9yTnU1Slg1N0c0dnNya1JhN3JEUURsNDI5dEdkT3RYYVJYK3dOb0FESmI5V0psOFlLOW5hUFkyNExkZ3FkOXRydEw2VUoyaTc5ek1Qclk0cjhIQWFQaXlxc0REQmRPVFdhanN5VmhOODFuU0JCQ0tBPT0=",
  "errors": null
}
```

**Response code: 200**

**Validation**

We have added a layer of validation here. We expect the the request to receive within "5 mins" from the time mentioned in "timeStamp" field of Device Info. The time "+5 mins" is configurable using the below property.

*Property:* `masterdata.registerdevice.timestamp.validate=+5`

If any request comes after 5 mins, then we would throw an exception.

**Signed Response**

The response received is grouped into three parts as Header, Payload and Signature which is in JWT (Java Web Token) format.

**Header**

Encoded Header:

`eyJhbGciOiJSUzI1NiIsInR5cGUiOiJKV1MifQ==`

Decoded Header:

```
{
  "alg": "RS256",
  "type": "JWS"
}
```

**Payload**

Encoded Payload:

```
eyJzdGF0dXMiOiJSRUdJU1RFUkVEIiwiZGlnaXRhbElkIjoiZXlKelpYSnBZV3hPYnlJNklqRTRNREV4TmpBNU9USWlMQ0prWlhacFkyVlFjbTkyYVdSbGNpSTZJbE5aVGtOQ1dWUkZJaXdpWkdWMmFXTmxVSEp2ZG1sa1pYSkpaQ0k2SWxOWlRrTkNXVlJGTGsxRE1ERkJJaXdpYldGclpTSTZJazFETURGQklpd2liVzlrWld3aU9pSlRUVWxFUTB3aUxDSmtZWFJsVkdsdFpTSTZJakl3TWpBdE1ERXRNVE5VTURjNk1qQTZOREl1TVRrMVdpSXNJblI1Y0dVaU9pSkdhVzVuWlhKd2NtbHVkQ0lzSW5OMVlsUjVjR1VpT2lKVGFXNW5iR1VpZlEiLCJkZXZpY2VDb2RlIjoiOGNkNDI4NjQtMmNkYy00MDY3LThkMTEtNDBiMjVmZjhjNzYwIiwiZW52IjoibG9jYWwiLCJ0aW1lU3RhbXAiOiIyMDIwLTAxLTEzVDEyOjU1OjI5LjkxOFoifQ==
```

Decoded Payload:

```
{
  "status": "REGISTERED",
  "digitalId": "eyJzZXJpYWxObyI6IjE4MDExNjA5OTIiLCJkZXZpY2VQcm92aWRlciI6IlNZTkNCWVRFIiwiZGV2aWNlUHJvdmlkZXJJZCI6IlNZTkNCWVRFLk1DMDFBIiwibWFrZSI6Ik1DMDFBIiwibW9kZWwiOiJTTUlEQ0wiLCJkYXRlVGltZSI6IjIwMjAtMDEtMTNUMDc6MjA6NDIuMTk1WiIsInR5cGUiOiJGaW5nZXJwcmludCIsInN1YlR5cGUiOiJTaW5nbGUifQ",
  "deviceCode": "8cd42864-2cdc-4067-8d11-40b25ff8c760",
  "env": "local",
  "timeStamp": "2020-01-13T12:55:29.918Z"
}
```

Digital ID extracted from payload will be unsigned and will be base64 encoded. Encoded digital ID:

```
eyJzZXJpYWxObyI6IjE4MDExNjA5OTIiLCJkZXZpY2VQcm92aWRlciI6IlNZTkNCWVRFIiwiZGV2aWNlUHJvdmlkZXJJZCI6IlNZTkNCWVRFLk1DMDFBIiwibWFrZSI6Ik1DMDFBIiwibW9kZWwiOiJTTUlEQ0wiLCJkYXRlVGltZSI6IjIwMjAtMDEtMTNUMDc6MjA6NDIuMTk1WiIsInR5cGUiOiJGaW5nZXJwcmludCIsInN1YlR5cGUiOiJTaW5nbGUifQ
```

Decoded Digital ID:

```
{
  "serialNo": "1801160992",
  "deviceProvider": "Test Vendor",
  "deviceProviderId": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
  "make": "MC01A",
  "model": "TVSFD",
  "dateTime": "2020-02-16T07:20:42.195Z",
  "type": "Fingerprint",
  "deviceSubType": "Single"
}
```

**Signed Response**

Signed response from signature API:

```
dkd3Mlo2TStDT2JpM1lHY2Q1OFNJRkJ6T0E5bFZ6dUFlZnN3NHhQZzEzWE42LzAvWVZ6Qm0yNnpmZXFPRXdmWHNKQUN4aC9QNExuM2RHcjhSR2diZjEvRXgwNktCOEhhbEM1VjhPMFh4VGxmK3ZSZFlJeTZhbFh0cS8rY0s0VjRSYUpHYjVDL2kweHdzMFF3bHh0UEo4cFIvbnVrb1d5dzNNTmRDSkNZaVlGSkxVUUpKbnhyaEtYR3dvM1ZlcVNkaEYrMStjS1ZpSzFWSlQ5OHFsMjFhTUp0MGd4Wko1Rzg5V0lSbi9yTnU1Slg1N0c0dnNya1JhN3JEUURsNDI5dEdkT3RYYVJYK3dOb0FESmI5V0psOFlLOW5hUFkyNExkZ3FkOXRydEw2VUoyaTc5ek1Qclk0cjhIQWFQaXlxc0REQmRPVFdhanN5VmhOODFuU0JCQ0tBPT0=
```

**Failure response**

```
{
  "id": "io.mosip.masterdata.device.create",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-16T07:20:42.195Z",
  "errors": [{
	"errorCode": "KER-ATH-401",
	"message": "Authentication Failed"
  }],
  "response": null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                                                                     | Error Description                                                                                              |
| ----------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| KER-ATH-401 | Authentication Failed                                                             | If no role/invalid token is detected                                                                           |
| ADM-DPM-025 | Mandatory input parameter is missing                                              | If any mandatory input parameter is missing                                                                    |
| ADM-DPM-026 | Device Type does not exist                                                        | If Device Type received does not exist                                                                         |
| ADM-DPM-027 | Device Sub-Type does not exist                                                    | If Device Sub-Type received does not exist                                                                     |
| ADM-DPM-028 | Invalid Status received                                                           | If in Status, standard values are not received                                                                 |
| ADM-DPM-029 | For Device ID, Json value expected for a L0 Device                                | If in Device, a singed Json is not received if certification level is L0                                       |
| ADM-DPM-030 | Make/Model inside the Json does not match with the input                          | If Make/Model inside the digital ID does not match with details received in input                              |
| ADM-DPM-031 | Device Provider details inside the Json does not match with the input             | If Device Provider ID/Device Provider name inside the digital ID does not match with details received in input |
| ADM-DPM-032 | Device Provider ID/Name does not exist in the list of Registered Device Providers | If Device Provider ID/Name does not exist against the Device Provider Details                                  |
| ADM-DPM-034 | Invalid Purpose received                                                          | If in purpose, standard values are not received                                                                |
| ADM-DPM-036 | Error occurred while storing MDS Details                                          | If there an error from DB while registering the Device                                                         |
| MSD-RDS-001 | Time Stamp input is %s min after the current timestamp                            | When timestamp in device info is after the configured timestamp range                                          |
| MSD-RDS-001 | Time Stamp input is %s min before the current timestamp                           | When timestamp in device info is before the configured timestamp range                                         |

### DELETE /deregister/{deviceCode}

This service deregisters a device from the platform and also created a history record for the device.

#### Resource URL

`DELETE https://{base_url}/v1/masterdata/registereddevices/deregister/{deviceCode}`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Parameters

| Name       | Required | Description                    | Default Value | Example |
| ---------- | -------- | ------------------------------ | ------------- | ------- |
| deviceCode | Yes      | This is the code of the device | NA            | NA      |

#### Response

**Success response**

```
{
  "id": "io.mosip.masterdata.device.delete",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-16T07:20:42.195Z",
  "errors": null,
  "response": {
	"status": "success",
	"message": "Device de-register successfully"
  }
}
```

**Response code: 200**

**Failure response**

```
{
  "id": "io.mosip.masterdata.device.delete",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-16T07:20:42.195Z",
  "errors": [{
	"errorCode": "KER-ATH-401",
	"message": "Authentication Failed"
  }],
  "response": null
}
```

**Response code: 200**

### PUT /registereddevices/status

This service updates status of the device. The history is persisted

#### Resource URL

`PUT /registereddevices/status?devicecode='70959dd5-e45f-438a-9ff8-9b263908e572'&status='REVOKED'`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Parameters

| Name       | Required | Description                    | Default Value | Example                          |
| ---------- | -------- | ------------------------------ | ------------- | -------------------------------- |
| deviceCode | Yes      | This is the code of the device | NA            | NA                               |
| status     | Yes      | This is the code of the device | NA            | REGISTERED or RETIRED or REVOKED |

#### Response

**Success response**

```
{
	"id": "io.mosip.masterdata.device.update",
	"version": "1.0",
	"metadata": {},
	"responsetime": "2020-02-16T07:20:42.195Z",
	"errors": null,
	"response": {
		"status": "success",
		"message": "Device de-register successfully"
	}
}
```

**Response code: 200**

**Failure response**

```
{
	"id": "io.mosip.masterdata.device.update",
	"version": "1.0",
	"metadata": {},
	"responsetime": "2020-02-16T07:20:42.195Z",
	"errors": [{
		"errorCode": "KER-ATH-401",
		"message": "Authentication Failed"
	}],
	"response": null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                               | Error Description                                      |
| ----------- | ------------------------------------------- | ------------------------------------------------------ |
| KER-ATH-401 | Authentication Failed                       | If no role/invalid token is detected                   |
| ADM-DPM-036 | Mandatory input parameter is missing        | If any mandatory input parameter is missing            |
| ADM-DPM-037 | Invalid Status received                     | If in Status, standard values are not received         |
| ADM-DPM-038 | Error occurred while updating Device Status | If there an error from DB while updating Device Status |

### POST /deviceprovidermanagement/validate

This service will validate the device details from the list of registered devices.

#### Resource URL

`POST https://{base_url}/masterdata/deviceprovidermanagement/validate`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Request Parameters

| Name                 | Required | Description                                          | Default Value | Example              |
| -------------------- | -------- | ---------------------------------------------------- | ------------- | -------------------- |
| deviceCode           | Yes      | Device ID of the device                              |               |                      |
| digitalId            | Yes      | JSON object consists of device details               |               |                      |
| deviceServiceVersion | Yes      | Device service version of the MDS                    |               |                      |
| timeStamp            | No       | Timestamp in local data time format of history table |               |                      |
| purpose              | No       | This is the purpose of the device                    | NA            | AUTH or REGISTRATION |

If timestamp is provided, then validate device using history data If purpose is provided, then validate purpose of device

#### Request

```
{
  "id": "io.mosip.masterdata.device.validate",
  "metadata": null,
  "request": {
    "deviceCode": "70959dd5-e45f-438a-9ff8-9b263908e572",
    "deviceServiceVersion": "TestSwVersion1",
    "timestamp": "2020-02-16T07:20:42.195Z"
    "purpose": "AUTH"
    "digitalId": {
      "serialNo": "1801160992",
      "make": "MC01A",
      "model": "TVSFD",
      "type": "Fingerprint",
      "deviceSubType": "Single",
      "dp": "Test Vendor",
      "dpId": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
      "dateTime": "2020-02-16T07:20:42.195Z"
    }
  },
  "version": "1.0",
  "requesttime": "2020-02-16T16:34:22.890Z"
}
```

#### Response

**Success response**

```
{
  "id": "io.mosip.masterdata.device.validate",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-16T06:12:52.994Z",
  "errors": null,
  "response":  [
    {
      "status": "Valid",
      "message": "Device details validated successfully"
    }
  ],
}
```

**Response code: 200**

**Failure response**

```
{
  "id": "io.mosip.masterdata.device.validate",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-16T06:12:52.994Z",
  "errors": [
    {
      "errorCode": "KER-MSD-500",
      "message": "Internal Server Error"
    }
  ],
 "response": null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                                            | Error Description                                                |
| ----------- | -------------------------------------------------------- | ---------------------------------------------------------------- |
| KER-MSD-500 | Internal Server Error                                    | If system error occurs                                           |
| KER-ATH-403 | Forbidden                                                | If unauthorized role detected                                    |
| KER-ATH-401 | Authentication Failed                                    | If no role/invalid token is detected                             |
| ADM-DPM-001 | Device does not exist                                    | If the Device does not exist                                     |
| ADM-DPM-002 | Device is Revoked/Retired                                | If the Device exist and is in Revoked/Retired                    |
| ADM-DPM-003 | Device Provider does not exist                           | If the Device Provider does not exist                            |
| ADM-DPM-004 | Device Provider is marked Inactive                       | If the Device Provider exist and is in Inactive State            |
| ADM-DPM-005 | MDS does not exist                                       | If the MDS does not exist                                        |
| ADM-DPM-006 | MDS is marked Inactive                                   | If the MDS exist and is in Inactive State                        |
| ADM-DPM-007 | Software version does not match against the Service ID   | If the Software version does not match the Service ID received   |
| ADM-DPM-008 | Device Provider ID does not match against the Service ID | If the Device provider ID does not match the Service ID received |
| ADM-DPM-009 | Error occurred while checking a Device Details           | If there an error from DB while checking device details          |

## MDS API

* [POST /mosipdeviceservice](#post-mosipdeviceservice)
* [PUT /mosipdeviceservice](#put-mosipdeviceservice)

### POST /mosipdeviceservice

This service will create the MDS which are used in the MOSIP platform.

#### Resource URL

`POST https://{base_url}/v1/masterdata/mosipdeviceservice`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Parameters

| Name              | Required | Description                  | Default Value | Example |
| ----------------- | -------- | ---------------------------- | ------------- | ------- |
| id                | Yes      | ID of the MDS                |               |         |
| deviceProviderId  | Yes      | Deviceproviderid of the MDS  |               |         |
| regDeviceSubCode  | Yes      | Devicetypecode of the MDS    |               |         |
| regDeviceTypeCode | Yes      | Devicesubtypecode of the MDS |               |         |
| swversion         | Yes      | Software version of the MDS  |               |         |
| swBinaryHash      | Yes      | Binary hash of the MDS       |               |         |
| make              | Yes      | Make of the MDS              |               |         |
| model             | Yes      | Model of the MDS             |               |         |
| swCreateDateTime  | Yes      | Created date time of MDS     |               |         |
| swExpiryDateTime  | Yes      | Expiry date time of MDS      |               |         |

#### Request

```
{
  "id": "io.mosip.masterdata.mds.create",
  "metadata": {},
  "request": {
	"deviceProviderId": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
	"isActive": true,
	"make": "MC01A",
	"model": "TVSFD",
	"regDeviceSubCode": "Single",
	"regDeviceTypeCode": "Finger",
	"swBinaryHash": "Test Hash",
	"swCreateDateTime": "2020-02-10T06:12:52.994Z",
	"swExpiryDateTime": "2021-02-10T06:12:52.994Z",
	"swVersion": "TestSwVersion1"
  },
  "requesttime": "2020-02-10T06:12:52.994Z",
  "version": "1.0"
}
```

#### Response

**Success response**

```
{
  "id": "io.mosip.masterdata.mds.create",
  "version": "1.0",
  "responsetime": "2020-02-10T06:12:52.994Z",
  "metadata": null,
  "response": {
	"isActive": true,
	"createdBy": "110006",
	"createdDateTime": "2020-02-10T06:12:52.994Z",
	"updatedBy": null,
	"updatedDateTime": null,
	"isDeleted": null,
	"deletedDateTime": null,
	"id": "0f343b65-aba2-44d2-b836-e7511270b1ab",
	"swVersion": "TestSwVersion1",
	"deviceProviderId": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
	"regDeviceTypeCode": "Finger",
	"regDeviceSubCode": "Single",
	"make": "MC01A",
	"model": "TVSFD",
	"swCreateDateTime": "2020-02-10T06:12:52.994Z",
	"swExpiryDateTime": "2021-02-10T06:12:52.994Z",
	"swBinaryHash": "Test Hash"
  },
  "errors": null
}
```

**Response code: 200**

**Failure response**

```
{
  "id": "io.mosip.masterdata.mds.create",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-10T06:12:52.994Z",
  "errors": [
    {
      "errorCode": "KER-ATH-401",
      "message": "Authentication Failed"
    }
  ],
 "response": null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                                                  | Error Description                                                         |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| KER-ATH-401 | Authentication Failed                                          | If no role/invalid token is detected                                      |
| ADM-DPM-020 | Mandatory input parameter is missing                           | If any mandatory input parameter is missing                               |
| ADM-DPM-021 | MDS Details already exist                                      | If the MDS Details already exist                                          |
| ADM-DPM-039 | Device Provider ID not found in the list of Device Providers   | Device Provider ID received does not exist in the Device Provider Table   |
| ADM-DPM-040 | Device Type Code not found in the list of Device Types         | Device Type Code received does not exist in the Device Type Table         |
| ADM-DPM-041 | Device Sub Type Code not found in the list of Device Sub Types | Device Sub Type Code received does not exist in the Device Sub Type Table |

### PUT /mosipdeviceservice

This service will update the MDS which are used in the MOSIP platform.

#### Resource URL

`PUT https://{base_url}/v1/masterdata/mosipdeviceservice`

#### Resource details

| Resource Details        | Description |
| ----------------------- | ----------- |
| Response format         | JSON        |
| Requires Authentication | Yes         |

#### Parameters

| Name              | Required | Description                  | Default Value | Example |
| ----------------- | -------- | ---------------------------- | ------------- | ------- |
| id                | Yes      | ID of the MDS                |               |         |
| deviceProviderId  | Yes      | Deviceproviderid of the MDS  |               |         |
| regDeviceSubCode  | Yes      | Devicetypecode of the MDS    |               |         |
| regDeviceTypeCode | Yes      | Devicesubtypecode of the MDS |               |         |
| swversion         | Yes      | Software version of the MDS  |               |         |
| swBinaryHash      | Yes      | Binary hash of the MDS       |               |         |
| make              | Yes      | Make of the MDS              |               |         |
| model             | Yes      | Model of the MDS             |               |         |
| swCreateDateTime  | Yes      | Created date time of MDS     |               |         |
| swExpiryDateTime  | Yes      | Expiry date time of MDS      |               |         |

#### Request

```
{
  "id": "io.mosip.masterdata.mds.update",
  "metadata": {},
  "request": {
    "active": true,
    "deviceProviderId": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
    "id": "0f343b65-aba2-44d2-b836-e7511270b1ab",
    "make": "MC01A",
    "model": "TVSFD",
    "regDeviceSubCode": "Single",
    "regDeviceTypeCode": "Finger",
    "swBinaryHash": "Test Hash",
    "swCreateDateTime": "2020-02-10T06:12:52.994Z",
    "swExpiryDateTime": "2022-02-10T06:12:52.994Z",
    "swVersion": "TestSwVersion1"
  },
  "requesttime": "2020-02-10T06:12:52.994Z",
  "version": "1.0"
}
```

#### Response

**Success response**

```
{
  "id": "io.mosip.masterdata.mds.update",
  "version": "1.0",
  "responsetime": "2020-02-11T06:12:52.994Z",
  "metadata": null,
  "response": {
    "isActive": true,
    "createdBy": "110006",
    "createdDateTime": "2020-02-10T06:12:52.994Z",
	"updatedBy": "110005",
    "updatedDateTime": "2020-02-11T06:12:52.994Z",
    "isDeleted": null,
    "deletedDateTime": null,
    "id": "0f343b65-aba2-44d2-b836-e7511270b1ab",
    "swVersion": "v2",
    "deviceProviderId": "0e90bb45-cc9b-4521-9644-72755f6aa1e9",
    "regDeviceTypeCode": "Finger",
    "regDeviceSubCode": "Single",
    "make": "MC01A",
    "model": "TVSFD",
    "swCreateDateTime": "2020-02-10T06:12:52.994Z",
    "swExpiryDateTime": "2022-02-10T06:12:52.994Z",
    "swBinaryHash": "Test Hash"
  },
  "errors": null
}
```

**Response code: 200**

**Failure Response**

```
{
  "id": "io.mosip.masterdata.mds.update",
  "version": "1.0",
  "metadata": {},
  "responsetime": "2020-02-11T06:12:52.994Z",
  "errors": [
    {
      "errorCode": "KER-ATH-401",
      "message": "Authentication Failed"
    }
  ],
 "response": null
}
```

**Response code: 200**

#### Failure details

| Error Code  | Error Message                                                  | Error Description                                                         |
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| KER-ATH-401 | Authentication Failed                                          | If no role/invalid token is detected                                      |
| ADM-DPM-020 | Mandatory input parameter is missing                           | If any mandatory input parameter is missing                               |
| ADM-DPM-021 | MDS Details already exist                                      | If the MDS Details already exist                                          |
| ADM-DPM-039 | Device Provider ID not found in the list of Device Providers   | Device Provider ID received does not exist in the Device Provider Table   |
| ADM-DPM-040 | Device Type Code not found in the list of Device Types         | Device Type Code received does not exist in the Device Type Table         |
| ADM-DPM-041 | Device Sub Type Code not found in the list of Device Sub Types | Device Sub Type Code received does not exist in the Device Sub Type Table |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mosip.io/1.1.5/apis/device-management-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.