<commit_before>Device Management API
=====================
The Device Management API is a RESTful service that allows you to list, register, revoke, restore, and delete devices or applications which need to send OMF messages to the community ingress gateway.

API Authentication and Authorization
====================================
The API authenticates incoming connections using Azure Active Directory (AAD), and any client that calls into the API must use the OAuth2 implicit flow with a valid AAD identity.  More information on AAD authentication can be found here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-authentication-scenarios/ and here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-dev-understanding-oauth2-implicit-grant/

Once a connection is authenticated with a valid AAD identity, that identity is then checked to insure it is associated with an administrator role or group.  Only administrators are allowed to access the API.  A non-administrator that attempts to call the API will be rejected with an HTTP "403 Forbidden" message.

API Methods
===========
The API is hosted at https://<host>/devicemanagement.  Device information is contained in a JSON object called the ``DeviceModel`` and has the following format::

    {
        "TenantId": "string",
        "DeviceId": "string",
        "DeviceName": "string",
        "QiNamespace": "string",
        "Revoked": false,
        "ProducerToken": "string" 
    }

- **TenantId:** This identifies the owner of the device.  This is assigned by the system by looking up the tenant associated with the logged in user making the API call.

- **DeviceId:** This is a unique identifier for the device which is generated by the API during registration.

- **DeviceName:** A name for the device, specified by the user at the time of registration.

- **QiNamespace:** This identifies which Qi Namespace the device will write to.  In Qi, all writes must be assigned a namespace.

- **Revoked:** This indicates whether the device is present in the ingress gateway's blacklist.  A device on the blacklist will prevent any client associated with that device's token from sending data. 

- **ProducerToken:** This is a set of claims along with a cryptographic signature that verifies that the token is legitimate and has not been tampered with.  It is used when building OMF messages that are sent to the ingress gateway.

For examples on how to use the API methods, see https://<host>/swagger/ui/index


HTTP GET
---------
**devicemanagement/device/{deviceId}**
    
    Gets the information for a single device with the specified DeviceId.

**devicemanagement/devices**

    Gets a list of all devices associated with the tenant of the current identity.

HTTP POST
----------
**devicemanagement/device**

    Registers a new device or updates an existing device with properties that match the DeviceModel passed in with the message body.  Returns a DeviceModel with the system generated DeviceId and ProducerToken properties populated.

**devicemanagement/devices**

    Registers a set of new devices or updates existing devices with properties that match the DeviceModels in an array inside the message body.  Returns an array of DeviceModels with the system generated DeviceId and ProducerToken properties populated.

When registering a new device, the ``DeviceName`` and ``QiNamespace`` properties of the passed in DeviceModel must be assigned.  When editing an existing device, a valid existing ``DeviceId`` must be specified as well.

If a DeviceModel for an existing device is passed in during a POST operation and the Revoked property does not match the property of the existing device, the device will be added or removed from the revocation blacklist according to the newly posted value.

HTTP PUT
---------
**devicemanagement/device/{deviceId}/revoke**

    Adds the device to the revocation blacklist which prevents any client from sending OMF messages to the ingress gateway using that devices security token.  This is useful for temporarily blocking writes from a particular device.

**devicemanagement/device/{deviceId}/restore**

    Removes a device from the revocation blacklist, allowing it to send data to the ingress gateway.

HTTP DELETE
------------
**devicemanagement/device/{deviceId}**

    Deletes the device associated with the deviceId.  Deleting a device will revoke the security token associated with the device so that it can no longer be used.  Deletions are permanent and can not be undone.

Security Tokens
===============
When a device is registered using the API, a security token called the "ProducerToken" is generated and returned to the caller.  These tokens are required to be added to the headers of OMF messages that are sent to the ingress gateway from the registered device.

The security token contains information that uniquely identifies the device.  The following information can be found in the token:

- **Device ID:** This is a unique identifier for the device which is generated by the API during registration.

- **Tenant ID:** The identifies the owner of the device.

- **Qi Namespace:** This identifies which Qi Namespace the device will write to.  In Qi, all writes must be assigned a namespace.

- **Expiration Time**: This determines when the security token expires.  If the device has the ability to re-register with the API, it is recommended to keep this duration short and to periodically re-register before this token expires.  Doing this will reduce the time a token can be used to authenticate if the token is ever compromised.  Devices that do not have the ability to use the API to renew tokens and can store their tokens securely should choose a long expiration time.

- **Signature:** This is a cryptographic signature that verifies that the token is legitimate and has not been tampered with.  It uses the HMAC-SHA256 algorithm.

The security token generated by the API during device registration is a bearer token, meaning that any client that presents the token to the ingress gateway will be able to authenticate as that device, assuming the token is valid.  Because of this, it is imperative that the token be stored in a secure location on the device that is only accessible to the application sending data to the ingress service.  If that token is ever compromised, an unauthorized client can impersonate the device until the token expires or is revoked.

This token should never be transported over an unsecure network connection.  If, for example, you have a management service that does token registration and renewal with the API and then pushes the token down to the device, make sure your network connection to the device is using SSL/TLS or other secure protocol.  The device management API is only accessible using HTTPS.

Since each OMF message contains the token, never send OMF data to a service that does not implement SSL/TLS or other secure protocol.  The community ingress gateway will not accept insecure protocol connections, but if you use a proxy or data aggregator such as a message broker, make sure connections to any services that accept your OMF messages are secure and that the services you are sending the messages to are trusted.


<commit_msg>* Fixed typo * Added more detail on requirements for PUT operations<commit_after>Device Management API
=====================
The Device Management API is a RESTful service that allows you to list, register, revoke, restore, and delete devices or applications which need to send OMF messages to the community ingress gateway.

API Authentication and Authorization
====================================
The API authenticates incoming connections using Azure Active Directory (AAD), and any client that calls into the API must use the OAuth2 implicit flow with a valid AAD identity.  More information on AAD authentication can be found here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-authentication-scenarios/ and here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-dev-understanding-oauth2-implicit-grant/

Once a connection is authenticated with a valid AAD identity, that identity is then checked to insure it is associated with an administrator role or group.  Only administrators are allowed to access the API.  A non-administrator that attempts to call the API will be rejected with an HTTP "403 Forbidden" message.

API Methods
===========
The API is hosted at https://<host>/devicemanagement.  Device information is contained in a JSON object called the ``DeviceModel`` and has the following format::

    {
        "TenantId": "string",
        "DeviceId": "string",
        "DeviceName": "string",
        "QiNamespace": "string",
        "Revoked": false,
        "ProducerToken": "string" 
    }

- **TenantId:** This identifies the owner of the device.  This is assigned by the system by looking up the tenant associated with the logged in user making the API call.

- **DeviceId:** This is a unique identifier for the device which is generated by the API during registration.

- **DeviceName:** A name for the device, specified by the user at the time of registration.

- **QiNamespace:** This identifies which Qi Namespace the device will write to.  In Qi, all writes must be assigned a namespace.

- **Revoked:** This indicates whether the device is present in the ingress gateway's blacklist.  A device on the blacklist will prevent any client associated with that device's token from sending data. 

- **ProducerToken:** This is a set of claims along with a cryptographic signature that verifies that the token is legitimate and has not been tampered with.  It is used when building OMF messages that are sent to the ingress gateway.

For examples on how to use the API methods, see https://<host>/swagger/ui/index


HTTP GET
---------
**devicemanagement/device/{deviceId}**
    
    Gets the information for a single device with the specified DeviceId.

**devicemanagement/devices**

    Gets a list of all devices associated with the tenant of the current identity.

HTTP POST
----------
**devicemanagement/device**

    Registers a new device or updates an existing device with properties that match the DeviceModel passed in with the message body.  Returns a DeviceModel with the system generated DeviceId and ProducerToken properties populated.

**devicemanagement/devices**

    Registers a set of new devices or updates existing devices with properties that match the DeviceModels in an array inside the message body.  Returns an array of DeviceModels with the system generated DeviceId and ProducerToken properties populated.

When registering a new device, the ``DeviceName`` and ``QiNamespace`` properties of the passed in DeviceModel must be assigned.  When editing an existing device, a valid existing ``DeviceId`` must be specified as well.

If a DeviceModel for an existing device is passed in during a POST operation and the Revoked property does not match the property of the existing device, the device will be added or removed from the revocation blacklist according to the newly posted value.

HTTP PUT
---------
**devicemanagement/device/{deviceId}/revoke**

    Adds the device to the revocation blacklist which prevents any client from sending OMF messages to the ingress gateway using that devices security token.  This is useful for temporarily blocking writes from a particular device.

**devicemanagement/device/{deviceId}/restore**

    Removes a device from the revocation blacklist, allowing it to send data to the ingress gateway.
	
For PUTs to revoke and restore, the client does not need to pass the ``DeviceModel`` in the message body.  The deviceId in the resource path is all the information required from the client.

HTTP DELETE
------------
**devicemanagement/device/{deviceId}**

    Deletes the device associated with the deviceId.  Deleting a device will revoke the security token associated with the device so that it can no longer be used.  Deletions are permanent and can not be undone.

Security Tokens
===============
When a device is registered using the API, a security token called the "ProducerToken" is generated and returned to the caller.  These tokens are required to be added to the headers of OMF messages that are sent to the ingress gateway from the registered device.

The security token contains information that uniquely identifies the device.  The following information can be found in the token:

- **Device ID:** This is a unique identifier for the device which is generated by the API during registration.

- **Tenant ID:** This identifies the owner of the device.

- **Qi Namespace:** This identifies which Qi Namespace the device will write to.  In Qi, all writes must be assigned a namespace.

- **Expiration Time**: This determines when the security token expires.  If the device has the ability to re-register with the API, it is recommended to keep this duration short and to periodically re-register before this token expires.  Doing this will reduce the time a token can be used to authenticate if the token is ever compromised.  Devices that do not have the ability to use the API to renew tokens and can store their tokens securely should choose a long expiration time.

- **Signature:** This is a cryptographic signature that verifies that the token is legitimate and has not been tampered with.  It uses the HMAC-SHA256 algorithm.

The security token generated by the API during device registration is a bearer token, meaning that any client that presents the token to the ingress gateway will be able to authenticate as that device, assuming the token is valid.  Because of this, it is imperative that the token be stored in a secure location on the device that is only accessible to the application sending data to the ingress service.  If that token is ever compromised, an unauthorized client can impersonate the device until the token expires or is revoked.

This token should never be transported over an unsecure network connection.  If, for example, you have a management service that does token registration and renewal with the API and then pushes the token down to the device, make sure your network connection to the device is using SSL/TLS or other secure protocol.  The device management API is only accessible using HTTPS.

Since each OMF message contains the token, never send OMF data to a service that does not implement SSL/TLS or other secure protocol.  The community ingress gateway will not accept insecure protocol connections, but if you use a proxy or data aggregator such as a message broker, make sure connections to any services that accept your OMF messages are secure and that the services you are sending the messages to are trusted.



{'fraction_non_alphanumeric': 0.05849396384979657, 'fraction_numerical': 0.0010671646768491963, 'mean_word_length': 3.9780876494023905, 'pattern_counts': {'":': 12, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3302292', 'n_tokens_mistral': 3598, 'n_tokens_neox': 3332, 'n_words': 2129}