docs/1.3/api/device-registration/index.html - gerrit/www.eclipse.org/hono - Git at Google

 <!DOCTYPE html>
 <html lang="1.3" class="js csstransforms3d">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="Hugo 0.81.0" />
     <meta name="description" content="A set of micro-services for connecting millions of devices.">
 <meta name="author" content="The Eclipse Hono Project">

     <link rel="apple-touch-icon" sizes="180x180" href="/hono/docs/favicon/apple-touch-icon.png">
 <link rel="icon" type="image/png" sizes="48x48" href="/hono/docs/favicon/favicon-48x48.png">
 <link rel="icon" type="image/png" sizes="32x32" href="/hono/docs/favicon/favicon-32x32.png">
 <link rel="icon" type="image/png" sizes="16x16" href="/hono/docs/favicon/favicon-16x16.png">
 <link rel="manifest" href="/hono/docs/favicon/site.webmanifest">
 <link rel="mask-icon" href="/hono/docs/favicon/safari-pinned-tab.svg" color="#5bbad5">
 <link rel="shortcut icon" href="/hono/docs/favicon/favicon.ico">
 <meta name="msapplication-TileColor" content="#da532c">
 <meta name="msapplication-config" content="/hono/docs/favicon/browserconfig.xml">
 <meta name="theme-color" content="#ffffff">

     <title>Device Registration API Specification :: Eclipse Hono&trade; Vers.: 1.3</title>


     <link href="/hono/docs/css/nucleus.css?1626138728" rel="stylesheet">
     <link href="/hono/docs/css/fontawesome-all.min.css?1626138728" rel="stylesheet">
     <link href="/hono/docs/css/hybrid.css?1626138728" rel="stylesheet">
     <link href="/hono/docs/css/featherlight.min.css?1626138728" rel="stylesheet">
     <link href="/hono/docs/css/perfect-scrollbar.min.css?1626138728" rel="stylesheet">
     <link href="/hono/docs/css/auto-complete.css?1626138728" rel="stylesheet">
     <link href="/hono/docs/css/atom-one-dark-reasonable.css?1626138728" rel="stylesheet">
     <link href="/hono/docs/css/theme.css?1626138728" rel="stylesheet">
     <link href="/hono/docs/css/hugo-theme.css?1626138728" rel="stylesheet">

     <link href="/hono/docs/css/theme-hono.css?1626138728" rel="stylesheet">

     <link href="/hono/docs/css/hono.css?1626138728" rel="stylesheet">

     <script src="/hono/docs/js/jquery-3.3.1.min.js?1626138728"></script>

     <style>
       :root #header + #content > #left > #rlblock_left{
           display:none !important;
       }

         :not(pre) > code + span.copy-to-clipboard {
             display: none;
         }

     </style>

 <link rel="stylesheet" href="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css">


 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:site" content="@EclipseHono">
 <meta name="twitter:title" content="Device Registration API Specification :: Eclipse Hono&amp;trade; Vers.: 1.3">
 <meta name="twitter:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png">
 <meta name="twitter:description" content="A set of micro-services for connecting millions of devices.">


 <meta property="og:title" content="Device Registration API Specification :: Eclipse Hono&amp;trade; Vers.: 1.3" />
 <meta property="og:type" content="website" />
 <meta property="og:url" content="https://www.eclipse.org/hono/docs/1.3/api/device-registration//" />
 <meta property="og:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png" />

   </head>
   <body class="" data-url="/hono/docs/1.3/api/device-registration/">
     <nav id="sidebar" class="">


   <div id="header-wrapper">
     <div id="header">
       <a href="https://www.eclipse.org/hono/">
     <img src="/hono/docs/images/HONO-Logo_Bild-Wort_quer-w-310x120px.svg" alt="Hono logo" class="logo-img">
 </a>

     </div>

         <div class="searchbox">
     <label for="search-by"><i class="fas fa-search"></i></label>
     <input data-search-input id="search-by" type="search" placeholder="Search...">
     <span data-search-clear=""><i class="fas fa-times"></i></span>
 </div>

 <script type="text/javascript" src="/hono/docs/js/lunr.min.js?1626138728"></script>
 <script type="text/javascript" src="/hono/docs/js/auto-complete.js?1626138728"></script>
 <script type="text/javascript">

         var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/1.3";

 </script>
 <script type="text/javascript" src="/hono/docs/js/search.js?1626138728"></script>


   </div>

     <div class="highlightable">
     <ul class="topics">


     <li data-nav-id="/hono/docs/1.3/concepts/" title="Concepts" class="dd-item


         ">
       <a href="/hono/docs/1.3/concepts/">
           <i class="far fa-lightbulb"></i> Concepts

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.3/concepts/device-identity/" title="Device Identity" class="dd-item ">
         <a href="/hono/docs/1.3/concepts/device-identity/">
         Device Identity

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/concepts/tenancy/" title="Multi-Tenancy" class="dd-item ">
         <a href="/hono/docs/1.3/concepts/tenancy/">
         Multi-Tenancy

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/concepts/device-provisioning/" title="Device Provisioning" class="dd-item ">
         <a href="/hono/docs/1.3/concepts/device-provisioning/">
         Device Provisioning

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/concepts/connecting-devices/" title="Connecting Devices" class="dd-item ">
         <a href="/hono/docs/1.3/concepts/connecting-devices/">
         Connecting Devices

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/concepts/device-notifications/" title="Device Notifications" class="dd-item ">
         <a href="/hono/docs/1.3/concepts/device-notifications/">
         Device Notifications

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/concepts/command-and-control/" title="Command &amp; Control" class="dd-item ">
         <a href="/hono/docs/1.3/concepts/command-and-control/">
         Command &amp; Control

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/concepts/resource-limits/" title="Resource limits" class="dd-item ">
         <a href="/hono/docs/1.3/concepts/resource-limits/">
         Resource limits

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/concepts/connection-events/" title="Connection Events" class="dd-item ">
         <a href="/hono/docs/1.3/concepts/connection-events/">
         Connection Events

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.3/user-guide/" title="User Guide" class="dd-item


         ">
       <a href="/hono/docs/1.3/user-guide/">
           <i class="fas fa-book-reader"></i> User Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.3/user-guide/mongodb-based-device-registry/" title="MongoDB Based Device Registry" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/mongodb-based-device-registry/">
         MongoDB Based Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/user-guide/file-based-device-registry/" title="File Based Device Registry" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/file-based-device-registry/">
         File Based Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/user-guide/http-adapter/" title="HTTP Adapter" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/http-adapter/">
         HTTP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/user-guide/mqtt-adapter/" title="MQTT Adapter" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/mqtt-adapter/">
         MQTT Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/user-guide/amqp-adapter/" title="AMQP Adapter" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/amqp-adapter/">
         AMQP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/user-guide/coap-adapter/" title="CoAP Adapter" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/coap-adapter/">
         CoAP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/user-guide/kura-adapter/" title="Kura Adapter" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/kura-adapter/">
         Kura Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/user-guide/sigfox-adapter/" title="Sigfox Adapter" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/sigfox-adapter/">
         Sigfox Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/user-guide/jmeter_load_tests/" title="Load Tests with JMeter" class="dd-item ">
         <a href="/hono/docs/1.3/user-guide/jmeter_load_tests/">
         Load Tests with JMeter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.3/admin-guide/" title="Admin Guide" class="dd-item


         ">
       <a href="/hono/docs/1.3/admin-guide/">
           <i class="fas fa-sliders-h"></i> Admin Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.3/admin-guide/common-config/" title="Common Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/common-config/">
         Common Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/auth-server-config/" title="Auth Server Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/auth-server-config/">
         Auth Server Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/mongodb-device-registry-config/" title="MongoDB Based Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/mongodb-device-registry-config/">
         MongoDB Based Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/file-based-device-registry-config/" title="File Based Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/file-based-device-registry-config/">
         File Based Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/device-connection-config/" title="Configuring the Device Connection Service" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/device-connection-config/">
         Device Connection Service Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/http-adapter-config/" title="HTTP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/http-adapter-config/">
         HTTP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/mqtt-adapter-config/" title="MQTT Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/mqtt-adapter-config/">
         MQTT Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/amqp-adapter-config/" title="AMQP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/amqp-adapter-config/">
         AMQP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/coap-adapter-config/" title="CoAP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/coap-adapter-config/">
         CoAP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/kura-adapter-config/" title="Kura Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/kura-adapter-config/">
         Kura Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/hono-client-configuration/" title="Hono Client Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/hono-client-configuration/">
         Hono Client Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/amqp-network-config/" title="AMQP 1.0 Messaging Network Configuration" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/amqp-network-config/">
         AMQP 1.0 Messaging Network Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/secure_communication/" title="Secure Communication" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/secure_communication/">
         Secure Communication

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/admin-guide/monitoring-tracing-config/" title="Monitoring &amp; Tracing" class="dd-item ">
         <a href="/hono/docs/1.3/admin-guide/monitoring-tracing-config/">
         Monitoring &amp; Tracing

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.3/dev-guide/" title="Developer Guide" class="dd-item


         ">
       <a href="/hono/docs/1.3/dev-guide/">
           <i class="fas fa-tools"></i> Developer Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.3/dev-guide/building_hono/" title="Building from Source" class="dd-item ">
         <a href="/hono/docs/1.3/dev-guide/building_hono/">
         Building from Source

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/dev-guide/amqp_adapter_client/" title="AMQP Adapter Client for Java" class="dd-item ">
         <a href="/hono/docs/1.3/dev-guide/amqp_adapter_client/">
         AMQP Adapter Client for Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/dev-guide/java_client_consumer/" title="Consuming Messages from Java" class="dd-item ">
         <a href="/hono/docs/1.3/dev-guide/java_client_consumer/">
         Consuming Messages from Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/dev-guide/custom_http_adapter/" title="Implement a Custom Hono HTTP Protocol Adapter" class="dd-item ">
         <a href="/hono/docs/1.3/dev-guide/custom_http_adapter/">
         Implement a Custom Hono HTTP Protocol Adapter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.3/api/" title="API" class="dd-item
         parent


         ">
       <a href="/hono/docs/1.3/api/">
           &nbsp;<i class='fas fa-plug'></i>&nbsp;API

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.3/api/telemetry/" title="Telemetry API Specification" class="dd-item ">
         <a href="/hono/docs/1.3/api/telemetry/">
         Telemetry API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/event/" title="Event API Specification" class="dd-item ">
         <a href="/hono/docs/1.3/api/event/">
         Event API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/command-and-control/" title="Command &amp; Control API Specification" class="dd-item ">
         <a href="/hono/docs/1.3/api/command-and-control/">
         Command &amp; Control API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/tenant/" title="Tenant API Specification" class="dd-item ">
         <a href="/hono/docs/1.3/api/tenant/">
         Tenant API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/device-connection/" title="Device Connection API Specification" class="dd-item ">
         <a href="/hono/docs/1.3/api/device-connection/">
         Device Connection API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/device-registration/" title="Device Registration API Specification" class="dd-item active">
         <a href="/hono/docs/1.3/api/device-registration/">
         Device Registration API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/credentials/" title="Credentials API Specification" class="dd-item ">
         <a href="/hono/docs/1.3/api/credentials/">
         Credentials API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/authentication/" title="Authentication API Specification" class="dd-item ">
         <a href="/hono/docs/1.3/api/authentication/">
         Authentication API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/management/" title="Device Registry Management API Specification" class="dd-item ">
         <a href="/hono/docs/1.3/api/management/">
         Device Registry Management API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/api/metrics/" title="Metrics" class="dd-item ">
         <a href="/hono/docs/1.3/api/metrics/">
         Metrics

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.3/deployment/" title="Deployment" class="dd-item


         ">
       <a href="/hono/docs/1.3/deployment/">
           <i class="fas fa-shipping-fast"></i> Deployment

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.3/deployment/helm-based-deployment/" title="Helm based Deployment" class="dd-item ">
         <a href="/hono/docs/1.3/deployment/helm-based-deployment/">
         Helm based Deployment

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/deployment/openshift/" title="OpenShift / OKD" class="dd-item ">
         <a href="/hono/docs/1.3/deployment/openshift/">
         OpenShift / OKD

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/deployment/create-kubernetes-cluster/" title="Setting up a Kubernetes Cluster" class="dd-item ">
         <a href="/hono/docs/1.3/deployment/create-kubernetes-cluster/">
         Setting up a Kubernetes Cluster

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/deployment/resource-limitation/" title="Limiting Resource Usage" class="dd-item ">
         <a href="/hono/docs/1.3/deployment/resource-limitation/">
         Limiting Resource Usage

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.3/architecture/" title="Architecture" class="dd-item


         ">
       <a href="/hono/docs/1.3/architecture/">
           <i class="fas fa-landmark"></i> Architecture

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.3/architecture/component-view/" title="Component View" class="dd-item ">
         <a href="/hono/docs/1.3/architecture/component-view/">
         Component View

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.3/architecture/auth/" title="Authentication/Authorization" class="dd-item ">
         <a href="/hono/docs/1.3/architecture/auth/">
         Authentication/Authorization

         </a>
     </li>


         </ul>

     </li>


     </ul>


       <section id="shortcuts">
         <h3></h3>
         <ul>

               <li>
                   <a class="padding" href="https://www.eclipse.org/hono/" title="Hono&#39;s Homepage"><i class='fas fa-home'></i> Hono Home</a>
               </li>

               <li>
                   <a class="padding" href="https://www.eclipse.org/hono/getting-started/" title="Getting started with Eclipse Hono"><i class='fas fa-plane-departure'></i> Getting Started</a>
               </li>

         </ul>
       </section>


     <section id="prefooter">
       <hr/>
       <ul>

         <li>
           <div id="select-box-wrapper">
           <div id="select-box">
           <a class="padding">
             Version:&nbsp;
           <div class="select-style">
             <select id="select-language" onchange="location = this.value;">


                       <option id="stable" value="https://www.eclipse.org/hono/docs/api/device-registration/">stable (1.8)</option>


                       <option id="1.8" value="https://www.eclipse.org/hono/docs/1.8/api/device-registration/">1.8</option>


                       <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/api/device-registration/">1.7</option>


                       <option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/api/device-registration/">1.6</option>


                       <option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/api/device-registration/">1.5</option>


                       <option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/api/device-registration/">1.4</option>


                       <option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/api/device-registration/" selected>1.3</option>


                       <option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/api/device-registration/">1.2</option>


                       <option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/api/device-registration/">1.1</option>


                       <option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/api/device-registration/">1.0</option>


                       <option id="dev" value="https://www.eclipse.org/hono/docs/dev/api/device-registration/">dev</option>


         </select>
         <svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
           width="255px" height="255px" viewBox="0 0 255 255" style="enable-background:new 0 0 255 255;" xml:space="preserve">
           <g>
             <g id="arrow-drop-down">
               <polygon points="0,63.75 127.5,191.25 255,63.75 		" />
             </g>
           </g>
         </svg>
         </div>
         </a>
         </div>
         </div>
         </li>


       </ul>
     </section>

     <section id="footer">


 <p>&copy; 2021 <a href="https://www.eclipse.org/hono/">The Eclipse Hono Project</a></p>

 <p>
     Documentation built with
     <a href="https://gohugo.io/" target="_blank">Hugo</a>
     using the
     <a href="https://github.com/matcornic/hugo-theme-learn" target="_blank">Learn</a> theme.
 </p>

 <div class="eclipse-logo">
     <a href="https://www.eclipse.org" target="_blank">
         <img src="https://www.eclipse.org/hono/docs/images/eclipse_foundation_logo.svg"/>
     </a>
 </div>

     </section>
   </div>
 </nav>


         <section id="body">
         <div id="overlay"></div>


     <div class="old-version-hint">
         <p>This page refers to version <em>1.3</em>.
             You might want to use the <a href="https://www.eclipse.org/hono/docs/">current stable</a> version.
         </p>
     </div>


         <div class="padding highlightable">

               <div>
                 <div id="top-bar">


                   <div id="top-github-link">
                     <a class="github-link" title='Edit this page' href="https://github.com/eclipse/hono/edit/master/site/documentation/content/api/device-registration/index.md" target="blank">
                       <i class="fas fa-code-branch"></i>
                       <span id="top-github-link-text">Edit this page</span>
                     </a>
                   </div>


                 <div id="breadcrumbs" itemscope="" itemtype="http://data-vocabulary.org/Breadcrumb">
                     <span id="sidebar-toggle-span">
                         <a href="#" id="sidebar-toggle" data-sidebar-toggle="">
                           <i class="fas fa-bars"></i>
                         </a>
                     </span>

                   <span id="toc-menu"><i class="fas fa-list-alt"></i></span>

                   <span class="links">


             <a href='/hono/docs/1.3/'>Documentation</a> > <a href='/hono/docs/1.3/api/'>API</a> > Device Registration API Specification


                   </span>
                 </div>

                     <div class="progress">
     <div class="wrapper">
 <nav id="TableOfContents">
   <ul>
     <li><a href="#preconditions-for-invoking-the-device-registration-api">Preconditions for invoking the Device Registration API</a></li>
     <li><a href="#assert-device-registration">Assert Device Registration</a></li>
     <li><a href="#delivery-states">Delivery States</a></li>
   </ul>
 </nav>
     </div>
 </div>


               </div>
             </div>

         <div id="head-tags">

         </div>

         <div id="body-inner">

             <h1>

               Device Registration API Specification
             </h1>


 <p>The <em>Device Registration API</em> is used by Hono&rsquo;s protocol adapters to get information about devices connecting to the adapters.</p>
 <p>The Device Registration API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.</p>
 <p><a name="preconditions"></a></p>
 <h2 id="preconditions-for-invoking-the-device-registration-api">Preconditions for invoking the Device Registration API</h2>
 <ol>
 <li>Client has established an AMQP connection with the Device Registration service.</li>
 <li>Client has established an AMQP link in role <em>sender</em> on the connection using target address <code>registration/${tenant_id}</code>. This link is used by the client to send request messages to the Device Registration service.</li>
 <li>Client has established an AMQP link in role <em>receiver</em> on the connection using source address <code>registration/${tenant_id}/${reply-to}</code> where <em>reply-to</em> may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Device Registration service. This link&rsquo;s source address is also referred to as the <em>reply-to</em> address for the request messages.</li>
 </ol>
 <figure>
     <img src="preconditions.svg"
          alt="A client establishes an AMQP connection and the links required to invoke operations of the Device Registration service"/> <figcaption>
             <h4>Client connecting to Device Registration service</h4>
         </figcaption>
 </figure>

 <h2 id="assert-device-registration">Assert Device Registration</h2>
 <p>Clients use this command to verify that a device is registered for a particular tenant and is enabled.</p>
 <p><strong>Message Flow</strong></p>
 <p>The following sequence diagram illustrates the flow of messages involved in a <em>Client</em> asserting a device&rsquo;s registration status.</p>
 <figure>
     <img src="assert_success.svg"
          alt="A client sends a request message for asserting a device&#39;s registration status and receives a response containing the registration status"/> <figcaption>
             <h4>Client asserting a device&#39;s registration status</h4>
         </figcaption>
 </figure>

 <p><strong>Request Message Format</strong></p>
 <p>The following table provides an overview of the properties a client needs to set on a message to assert a device&rsquo;s registration status:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">AMQP Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>correlation-id</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>message-id</em></td>
 <td style="text-align:left">MAY contain an ID used to correlate a response message to the original request. If set, it is used as the <em>correlation-id</em> property in the response, otherwise the value of the <em>message-id</em> property is used. Either this or the <em>message-id</em> property MUST be set.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>device_id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST contain the ID of the device that is subject to the operation.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>gateway_id</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The identifier of the gateway that wants to get an assertion <em>on behalf</em> of another device (given in the <em>device_id</em> property).<br>An implementation SHOULD verify that the gateway exists, is enabled and is authorized to get an assertion for, and thus send data on behalf of, the device.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>message-id</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MAY contain an identifier that uniquely identifies the message at the sender side. Either this or the <em>correlation-id</em> property MUST be set.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>reply-to</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST contain the source address that the client wants to received response messages from. This address MUST be the same as the source address used for establishing the client&rsquo;s receive link (see <a href="#preconditions-for-invoking-the-device-registration-api">Preconditions</a>).</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>subject</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST be set to <code>assert</code>.</td>
 </tr>
 </tbody>
 </table>
 <p>The body of the message SHOULD be empty and will be ignored if it is not.</p>
 <p><strong>Response Message Format</strong></p>
 <p>The following table provides an overview of the properties contained in a response message to an <em>assert</em> request:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">AMQP Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>correlation-id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>message-id</em></td>
 <td style="text-align:left">Contains the <em>message-id</em> (or the <em>correlation-id</em>, if specified) of the request message that this message is the response to.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>content-type</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST be set to <code>application/json</code> if the invocation of the operation was successful and the body of the response message contains payload as described below.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>status</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>int</em></td>
 <td style="text-align:left">Contains the status code indicating the outcome of the operation. Concrete values and their semantics are defined below.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>cache_control</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">Contains an <a href="https://tools.ietf.org/html/rfc2616#section-14.9">RFC 2616</a> compliant <em>cache directive</em>. The directive contained in the property MUST be obeyed by clients that are caching responses.</td>
 </tr>
 </tbody>
 </table>
 <p>In case of a successful invocation of the operation, the body of the response message consists of a single <em>Data</em> section containing a UTF-8 encoded string representation of a single JSON object having the following properties:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">JSON Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>device-id</em></td>
 <td style="text-align:center"><em>yes</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The ID of the device that is subject of the assertion.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>via</em></td>
 <td style="text-align:center"><em>no</em></td>
 <td style="text-align:left"><em>array</em></td>
 <td style="text-align:left">The IDs (JSON strings) of gateways which may act on behalf of the device. This property MUST be set if any gateways are registered for the device. If the assertion request contained a <em>gateway_id</em> property and the response&rsquo;s <em>status</em> property has value <code>200</code> (indicating a successful assertion) then the array MUST at least contain the gateway ID from the request.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>defaults</em></td>
 <td style="text-align:center"><em>no</em></td>
 <td style="text-align:left"><em>object</em></td>
 <td style="text-align:left">Default values to be used by protocol adapters for augmenting messages from devices with missing information like a <em>content type</em>. It is up to the discretion of a protocol adapter if and how to use the given default values when processing messages published by the device.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>mapper</em></td>
 <td style="text-align:center"><em>no</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The name of a service that can be used to transform messages uploaded by the device before they are forwarded to downstream consumers. The client needs to map this name to the particular service to invoke.</td>
 </tr>
 </tbody>
 </table>
 <p>Below is an example for a payload of a response to an <em>assert</em> request for device <code>4711</code> which also includes a default <em>content-type</em> and a mapper service:</p>
 <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json">{
   <span style="color:#f92672">&#34;device-id&#34;</span>: <span style="color:#e6db74">&#34;4711&#34;</span>,
   <span style="color:#f92672">&#34;via&#34;</span>: [<span style="color:#e6db74">&#34;4712&#34;</span>],
   <span style="color:#f92672">&#34;defaults&#34;</span>: {
     <span style="color:#f92672">&#34;content-type&#34;</span>: <span style="color:#e6db74">&#34;application/vnd.acme+json&#34;</span>
   },
   <span style="color:#f92672">&#34;mapper&#34;</span>: <span style="color:#e6db74">&#34;my-payload-transformation&#34;</span>
 }
 </code></pre></div><p>The response message&rsquo;s <em>status</em> property may contain the following codes:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Code</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>200</em></td>
 <td style="text-align:left">OK, the device is registered for the given tenant and is enabled. The response message body contains the asserted device&rsquo;s registration status.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>400</em></td>
 <td style="text-align:left">Bad Request, the request message did not contain all mandatory properties.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>403</em></td>
 <td style="text-align:left">Forbidden, the gateway with the given <em>gateway id</em> either does not exist, is not enabled or is not authorized to get an assertion for the device with the given <em>device id</em>.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>404</em></td>
 <td style="text-align:left">Not Found, there is no device registered with the given <em>device id</em> within the given <em>tenant id</em> or the device is not enabled.</td>
 </tr>
 </tbody>
 </table>
 <p>For status codes indicating an error (codes in the <code>400 - 499</code> range) the message body MAY contain a detailed description of the error that occurred. In this case, the response message&rsquo;s <em>content-type</em> property SHOULD be set accordingly.</p>
 <h2 id="delivery-states">Delivery States</h2>
 <p>The Device Registration service uses the following AMQP message delivery states when receiving request messages from clients:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Delivery State</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>ACCEPTED</em></td>
 <td style="text-align:left">Indicates that the request message has been received and accepted for processing.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>REJECTED</em></td>
 <td style="text-align:left">Indicates that the request message has been received but cannot be processed. The disposition frame&rsquo;s <em>error</em> field contains information regarding the reason why. Clients should not try to re-send the request using the same message properties in this case.</td>
 </tr>
 </tbody>
 </table>

 <footer class="footline">

 </footer>


         </div>


       </div>

     <div id="navigation">


     </div>

     </section>

     <div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
       <div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
     </div>
     <script src="/hono/docs/js/clipboard.min.js?1626138729"></script>
     <script src="/hono/docs/js/perfect-scrollbar.min.js?1626138729"></script>
     <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1626138729"></script>
     <script src="/hono/docs/js/jquery.sticky.js?1626138729"></script>
     <script src="/hono/docs/js/featherlight.min.js?1626138729"></script>
     <script src="/hono/docs/js/highlight.pack.js?1626138729"></script>
     <script>hljs.initHighlightingOnLoad();</script>
     <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1626138729"></script>
     <script src="/hono/docs/js/learn.js?1626138729"></script>
     <script src="/hono/docs/js/hugo-learn.js?1626138729"></script>

     <link href="/hono/docs/mermaid/mermaid.css?1626138729" rel="stylesheet" />
     <script src="/hono/docs/mermaid/mermaid.js?1626138729"></script>
     <script>
         mermaid.initialize({ startOnLoad: true });
     </script>


 <script>
     (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
             new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
         j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
         'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
     })(window,document,'script','dataLayer','GTM-5WLCZXC');
 </script>


 <script src="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>

   </body>
 </html>