openapi: 3.0.1
info:
   title: Eclipse Hono™ Device Registry API
   description: |
      This API defines how to manage *Tenants*, *Devices*, and *Credentials*.
      It acts as a common basis which all Hono device registries should
      implement.

      ## Required APIs

      All operations, except the `tenants` resource are required. The tenant
      management might be outside of the scope of the device registry and
      managed by a higher level system. In this case all calls should simply
      return `404`. However, if the `tenants` resource is implemented, then all
      operations of it must be implemented.

      ## Security

      This specification explicitly leaves out the part of authenticating and
      authorizing users with the device registry. It is assumed that some form
      of token exchange between the user agent and the backend service will
      take place. Like for example HTTP basic authentication, or a bearer token.

      ## Code generation

      This model is not optimized for generating code from it. Code generators
      try to understand the model and then translate this into the require
      programming language. Even if the there would be no bugs in the code
      generators, that process would be already only be an approximation. So
      this model does focus in the description of the API, and doesn't tweak
      the specification in a way to please code generators.

   contact:
      name: Contact details
      url: https://www.eclipse.org/hono/community/get-in-touch/
   license:
      name: EPL-2.0
      url: https://www.eclipse.org/legal/epl-2.0/
   version: 1.0.0

externalDocs:
   description: Eclipse Hono™ web page
   url: https://eclipse.org/hono

tags:
   - name: tenants
     description: Tenant Management (optional)
     externalDocs:
        description: Hono Multi-Tenancy
        url: https://www.eclipse.org/hono/docs/concepts/tenancy/
   - name: devices
     description: Device registration
     externalDocs:
        description: Hono device identity
        url: https://www.eclipse.org/hono/docs/concepts/device-identity/
   - name: credentials
     description: Device credentials
     externalDocs:
        description: Hono device identity
        url: https://www.eclipse.org/hono/docs/concepts/device-identity/

servers:
   - url: '{server}/v1'
     variables:
        server:
           default: http://hono.eclipse.org:28080

security:
   - BearerAuth: []
   - BasicAuth: []

paths:

# Tenant API

   /tenants:

      post:
         tags:
            - tenants
         summary: Create new tenant with auto-generated ID
         operationId: createTenant
         requestBody:
            description: New tenant information
            content:
               application/json:
                  schema:
                     $ref: '#/components/schemas/Tenant'
            required: true
         responses:
            201:
               $ref: '#/components/responses/Created'
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'
            409:
               description: |
                  Indicates that an existing tenant uses a certificate authority with the same Subject DN.
                  If the client has no read access to the conflicting tenant then `403` should be returned instead.
               content:
                  application/json:
                     schema:
                        $ref: '#/components/schemas/Error'
                     example:
                        error: "Root Certificate Authority is already used by other tenant"
                        subject-dn: "CN=devices,OU=iot,O=ACME"

   /tenants/{tenantId}:

      parameters:
         - $ref: '#/components/parameters/tenantId'

      post:
         tags:
            - tenants
         summary: Create new tenant
         operationId: createTenantWithId
         requestBody:
            description: New tenant registration
            content:
               application/json:
                  schema:
                     $ref: '#/components/schemas/Tenant'
            required: true
         responses:
            201:
               $ref: '#/components/responses/Created'
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'
            409:
               description: |
                  Indicates that tenant with the given identifier already exists or that an existing tenant uses
                  a certificate authority with the same Subject DN.
                  If the client has no read access to the conflicting tenant then `403` should be returned instead.
               content:
                  application/json:
                     schema:
                        $ref: '#/components/schemas/Error'
                     example:
                        error: "tenant with given identifier already exists"

      get:
         tags:
            - tenants
         summary: Get tenant information
         operationId: getTenant
         responses:
            200:
               description: operation successful
               content:
                  application/json:
                     schema:
                        $ref: '#/components/schemas/Tenant'
               headers:
                  ETag:
                     description: Version of the resource
                     schema:
                        type: string
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            404:
               $ref: '#/components/responses/NotFound'

      put:
         tags:
            - tenants
         summary: Update tenant information
         operationId: updateTenant
         parameters:
            - $ref: '#/components/parameters/resourceVersion'
         requestBody:
            description: Tenant information
            content:
               application/json:
                  schema:
                     $ref: '#/components/schemas/Tenant'
            required: true
         responses:
            204:
               $ref: '#/components/responses/Updated'
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'
            404:
               $ref: '#/components/responses/NotFound'
            409:
               description: |
                  Indicates that an existing tenant uses a certificate authority with the same Subject DN.
                  If the client has no read access to the conflicting tenant then `403` should be returned instead.
               content:
                  application/json:
                     schema:
                        $ref: '#/components/schemas/Error'
                     example:
                        error: "Root Certificate Authority is already used by other tenant"
                        subject-dn: "CN=devices,OU=iot,O=ACME"
            412:
               $ref: '#/components/responses/ResourceVersionMismatch'

      delete:
         tags:
            - tenants
         summary: Delete tenant
         operationId: deleteTenant
         parameters:
            - $ref: '#/components/parameters/resourceVersion'
         responses:
            204:
               $ref: '#/components/responses/Deleted'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'
            404:
               $ref: '#/components/responses/NotFound'
            412:
               $ref: '#/components/responses/ResourceVersionMismatch'

# Device API

   /devices/{tenantId}:

      parameters:
         - $ref: '#/components/parameters/tenantId'

      post:
         tags:
            - devices
         summary: Create new device registration with auto-generated ID
         operationId: createDeviceRegistration
         requestBody:
            description: New device
            content:
               application/json:
                  schema:
                     $ref: '#/components/schemas/Device'
            required: true
         responses:
            201:
               $ref: '#/components/responses/Created'
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'

   /devices/{tenantId}/{deviceId}:

      parameters:
         - $ref: '#/components/parameters/tenantId'
         - $ref: '#/components/parameters/deviceId'

      post:
         tags:
            - devices
         summary: Create new device registration
         operationId: createDeviceRegistrationWithId
         requestBody:
            description: New device
            content:
               application/json:
                  schema:
                     $ref: '#/components/schemas/Device'
            required: true
         responses:
            201:
               $ref: '#/components/responses/Created'
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'
            409:
               $ref: '#/components/responses/AlreadyExists'

      get:
         tags:
            - devices
         summary: Get device registration information
         operationId: getRegistration
         responses:
            200:
               description: operation successful
               content:
                  application/json:
                     schema:
                        $ref: '#/components/schemas/Device'
               headers:
                  ETag:
                     description: Version of the resource
                     schema:
                        type: string
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            404:
               $ref: '#/components/responses/NotFound'

      put:
         tags:
            - devices
         summary: Update existing device registration
         operationId: updateRegistration
         parameters:
            - $ref: '#/components/parameters/resourceVersion'
         requestBody:
            description: Updated device registration
            content:
               application/json:
                  schema:
                     $ref: '#/components/schemas/Device'
            required: true
         responses:
            204:
               $ref: '#/components/responses/Updated'
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'
            404:
               $ref: '#/components/responses/NotFound'
            412:
               $ref: '#/components/responses/ResourceVersionMismatch'

      delete:
         tags:
            - devices
         summary: Delete device registration
         operationId: deleteRegistration
         parameters:
            - $ref: '#/components/parameters/resourceVersion'
         responses:
            204:
               $ref: '#/components/responses/Deleted'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'
            404:
               $ref: '#/components/responses/NotFound'
            412:
               $ref: '#/components/responses/ResourceVersionMismatch'

   /credentials/{tenantId}/{deviceId}:

      parameters:
         - $ref: '#/components/parameters/tenantId'
         - $ref: '#/components/parameters/deviceId'

      get:
         tags:
            - credentials
         summary: Get credentials set of a device.
         description: |
            Get the credentials set of a device. As long as the device is
            registered and the user has read access to it, this call should
            never return "not found".
            Depending on its implementation (or configuration), the device registry
            can either return all credentials information including full secret details or
            secret metadata along with the generated identifier (an `id` property).
            The identifier can be used for the follow-up `update` operation).
         operationId: getAllCredentials
         responses:
            200:
               description: Operation successful
               content:
                  application/json:
                     schema:
                        $ref: '#/components/schemas/CredentialsSet'
                     examples:
                        Full Credentials:
                           $ref: '#/components/examples/HashedPasswordExample'
                        Credentials Metadata:
                           $ref: '#/components/examples/MetaPasswordExample'
               headers:
                  ETag:
                     description: Version of the resource
                     schema:
                        type: string
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            404:
               $ref: '#/components/responses/NotFound'

      put:
         tags:
            - credentials
         summary: Update credentials set for registered device
         description: If the device registry is handling full secret details, the updated credential set
                      will be an exact match of the provided content. If it is using secret metadata,
                      data will be merged in based on the secret identities.
         operationId: setAllCredentials
         parameters:
            - $ref: '#/components/parameters/resourceVersion'
         requestBody:
            content:
               application/json:
                  schema:
                     $ref: '#/components/schemas/CredentialsSet'
                  examples:
                     Hashed Password:
                        $ref: '#/components/examples/HashedPasswordExample'
                     Plain Password:
                        $ref: '#/components/examples/PlainPasswordExample'
            required: true
         responses:
            204:
               $ref: '#/components/responses/Updated'
            400:
               $ref: '#/components/responses/MalformedRequest'
            401:
               $ref: '#/components/responses/Unauthorized'
            403:
               $ref: '#/components/responses/NotAllowed'
            404:
               $ref: '#/components/responses/NotFound'
            412:
               $ref: '#/components/responses/ResourceVersionMismatch'

components:

   schemas:

# Common schema

      Error:
         type: object
         additionalProperties: true
         required:
            - error
         properties:
            "error":
               type: string
               description: A human readable error message of what went wrong.

      DefaultProperties:
         type: object
         additionalProperties: true
         description: Defaults for properties defined on the tenant and device level.

      Extensions:
         type: object
         additionalProperties: true
         description: Allows arbitrary properties as extension to the ones
                      specified by the Hono API.

# Tenant schema

      Tenant:
         type: object
         additionalProperties: false
         properties:
            "enabled":
               type: boolean
               default: true
            "ext":
               $ref: '#/components/schemas/Extensions'
            "adapters":
               type: array
               description: |
                  A list of configuration options for certain types of protocol adapters.
                  If set then the array must not be empty.
                  Multiple entries for the same type are considered an error.
                  If not set, then all adapters are enabled using their respective
                  default configuration.
               items:
                  $ref: '#/components/schemas/Adapter'
            "defaults":
               $ref: '#/components/schemas/DefaultProperties'
            "minimum-message-size":
               type: integer
               default: 0
               description: |
                  The minimum message size in bytes. If set, then reported size of
                  telemetry, event and command messages is calculated as the minimum multiple
                  of the configured value that is greater than or equal to the messages
                  payload size.
            "resource-limits":
               $ref: '#/components/schemas/ResourceLimit'
            "tracing":
               $ref: '#/components/schemas/TracingConfig'
            "trusted-ca":
               type: array
               description: |
                  The set of root certificate authorities which are used for verifying the signature of
                  client certificates that devices use for authentication.
               items:
                  $ref: '#/components/schemas/TrustedCA'

      TrustedCA:
         type: object
         additionalProperties: false
         properties:
            "subject-dn":
               type: string
               description: |
                  The subject DN of the trusted root certificate in
                  the format defined by RFC 2253.
                  CAs of the *same* tenant may share the same subject DN, e.g.
                  allowing for the definition of overlapping validity periods.
                  However, CAs of *different* tenants must not share the same
                  subject DN in order to allow for the unique look up of a tenant by
                  the subject DN of one of its trusted CAs.
                  If the `cert` property is used to provide an X.509 certificate
                  then the subject DN is determined from the certificate and this
                  property is ignored.
                  Otherwise, i.e. if the `public-key` property is
                  used, this property is mandatory.
            "public-key":
               type: string
               format: byte
               description: |
                  The Base64 encoded binary DER encoding of the
                  trusted root certificate’s public key.
                  If the `cert` property is used to provide an
                  X.509 certificate then the public key is extracted
                  from the certificate and this property is ignored.
                  Either this property or `cert` must be set.
            "algorithm":
               type: string
               description: |
                  The algorithm used for the public key of the CA.
                  If the `cert` property is used to provide an
                  X.509 certificate then the algorithm is determined
                  from the certificate and this property is ignored.
                  Otherwise, i.e. if the `public-key` property is
                  used, this property must be set to the algorithm
                  used, if other than the default.
               default: RSA
               example: EC
            "not-before":
               type: string
               format: date-time
               description: |
                  The point in time from which on the certificate authority
                  may be used for authenticating devices.
                  If the `cert` property is used to provide an
                  X.509 certificate then the point in time is
                  determined from the certificate and this property is ignored.
                  Otherwise, i.e. if the `public-key` property is
                  used, this property is mandatory.
            "not-after":
               type: string
               format: date-time
               description: |
                  The point in time until which the certificate authority
                  may be used for authenticating devices.
                  If the `cert` property is used to provide an
                  X.509 certificate then the point in time is
                  determined from the certificate and this property is ignored.
                  Otherwise, i.e. if the `public-key` property is
                  used, this property is mandatory.
            "cert":
               type: string
               format: byte
               description: |
                  The Base64 encoded binary DER encoding of the trusted X.509 root certificate.
                  This property can be used as a convenient alternative to
                  specifying the `public-key`, `not-before`, `not-after` and
                  `algorithm` properties explicitly. Implementors of this
                  API may choose to support this property only for uploading
                  a certificate but then extract all relevant data and store
                  it in the properties described above.
                  Either this property or `public-key` must be set.
            "auto-provisioning-enabled":
               type: boolean
               default: false
               description: |
                  Indicates whether this trusted certificate may be used for automatically provisioning devices.
                  If it is *true* and the feature is supported by the device registry, the device registry
                  automatically provisions unregistered devices that authenticate with a client certificate
                  issued by this CA (i.e. creates registration and credentials).

         example:
            subject-dn: "CN=devices,OU=iot,O=ACME"
            public-key: "Tk9UIEEgUFVCTElDIEtFWQ=="
            algorithm: "EC"
            auto-provisioning-enabled: false
            not-before: "2019-10-03T13:45:16+02:00"
            not-after: "2021-10-03T00:00:00Z"

      Adapter:
         type: object
         additionalProperties: true
         required:
            - type
         properties:
            "type":
               type: string
            "enabled":
               type: boolean
               default: false
            "device-authentication-required":
               type: boolean
               default: true
            "ext":
               $ref: '#/components/schemas/Extensions'

      ResourceLimit:
         type: object
         additionalProperties: false
         properties:
            "max-connections":
               type: integer
               default: -1
               description: |
                  The maximum number of concurrent connections allowed from devices of this tenant.
                  A value of `-1` (the default) indicates that no limit is set.
            "max-ttl":
               type: integer
               default: -1
               description: |
                  The maximum time-to-live (in seconds) to use for events published by
                  devices of this tenant. Any default TTL value specified
                  at either the tenant or device level will be limited to
                  the max value specified here.
                  If this property is set to a value greater than -1 and no
                  default TTL is specified for a device, the max value will
                  be used for events published by the device.
                  A value of `-1` (the default) indicates that no limit is set.
                  Note that this property contains the TTL in seconds whereas
                  the AMQP 1.0 specification defines a message's ttl header
                  to use milliseconds.
            "data-volume":
               $ref: '#/components/schemas/DataVolume'
            "connection-duration":
               $ref: '#/components/schemas/ConnectionDuration'
            "ext":
               $ref: '#/components/schemas/Extensions'

      TracingConfig:
         type: object
         additionalProperties: false
         properties:
            "sampling-mode":
               type: string
               description: |
                  Defines if and how often OpenTracing spans are being
                  sampled when processing messages for this tenant.
                  The value `default` indicates that the underyling tracing
                  system's default sampling mode should be used.
                  The value `all` indicates that every span created for
                  messages of the tenant will be sampled.
                  The value `none` indicates that no spans should be sampled
                  at all for the tenant.
                  The mode defined here may be overridden for specific
                  devices by means of the `sampling-mode-per-auth-id`
                  property.
               default: default
               enum:
                  - default
                  - all
                  - none
            "sampling-mode-per-auth-id":
               type: object
               description: |
                  Defines if and how often OpenTracing spans are being
                  sampled when processing messages for specific devices
                  of this tenant.
                  This object contains a property for each device for which
                  specific behavior should be defined, using the device's
                  authentication identifier as the property name and
                  the device specific sampling mode as its value.
                  The value `default` indicates that the underyling tracing
                  system's default sampling mode should be used.
                  The value `all` indicates that every span created for
                  messages of the tenant will be sampled.
                  The value `none` indicates that no spans should be sampled
                  at all for the tenant.
                  The mode defined for a particular device has precedence
                  over the value defined by the `sampling-mode` property.
               additionalProperties:
                  type: string
                  description: |
                    The property name is the device's 'authentication identifier.
                  default: default
                  enum:
                     - default
                     - all
                     - none

      DataVolume:
         type: object
         additionalProperties: false
         required:
            - effective-since
         properties:
            "effective-since":
               type: string
               format: date-time
               description: The date-time on which the data volume limit came into effect.
            "max-bytes":
               type: integer
               default: -1
               description: The maximum number of bytes to be allowed for a tenant for the
                            defined period.
                            A value of -1 (the default) indicates that no limit is set.
            "period":
               $ref: '#/components/schemas/Period'

      ConnectionDuration:
         type: object
         additionalProperties: false
         required:
            - effective-since
         properties:
            "effective-since":
               type: string
               format: date-time
               description: The date-time on which the connection duration limit came into effect.
            "max-minutes":
               type: integer
               default: -1
               description: The maximum number of minutes to be allowed for a tenant for the
                  defined period.
                  A value of -1 (the default) indicates that no limit is set.
            "period":
               $ref: '#/components/schemas/Period'

      Period:
         type: object
         additionalProperties: false
         required:
            - mode
         properties:
            "mode":
               type: string
               description: The mode of the data usage caluclation. The supported modes by
                            the default resource limit checks implementation are "days"
                            and "monthly".
            "no-of-days":
               type: integer
               description: The number of days for which the data usage is to be calculated
                            if mode is set to "days". Otherwise, this property is ignored.
               
# Devices schema

      Device:
         type: object
         additionalProperties: false
         properties:
            "enabled":
               type: boolean
               default: true
            "defaults":
               $ref: '#/components/schemas/DefaultProperties'
            "via":
               type: array
               items:
                  type: string
               description: The device IDs of the gateways this device is assigned to.
            "ext":
               $ref: '#/components/schemas/Extensions'

# Credentials

      CredentialsSet:
         type: array
         description: A set of credentials. The entries in this list must be
                      unique by the composite key of `auth-id` and `type`.
         items:
            $ref: '#/components/schemas/TypedCredentials'

      TypedCredentials:
         additionalProperties: false
         oneOf:
            - $ref: '#/components/schemas/PasswordCredentials'
            - $ref: '#/components/schemas/PSKCredentials'
            - $ref: '#/components/schemas/X509CertificateCredentials'
         discriminator:
            propertyName: type
            mapping:
               "hashed-password": '#/components/schemas/PasswordCredentials'
               "psk": '#/components/schemas/PSKCredentials'
               "x509-cert": '#/components/schemas/X509CertificateCredentials'

      CommonCredentials:
         type: object
         additionalProperties: false
         required:
            - auth-id
            - type
         properties:
            "type":
               type: string
            "auth-id":
               type: string
            "enabled":
               type: boolean
               default: true
            "ext":
               $ref: '#/components/schemas/Extensions'

      PasswordCredentials:
         additionalProperties: false
         allOf:
            - $ref: '#/components/schemas/CommonCredentials'
            - type: object
              additionalProperties: false
              properties:
                 "secrets":
                    type: array
                    items:
                       $ref: '#/components/schemas/PasswordSecret'

      PSKCredentials:
         additionalProperties: false
         allOf:
            - $ref: '#/components/schemas/CommonCredentials'
            - type: object
              additionalProperties: false
              properties:
                 "secrets":
                    type: array
                    items:
                       $ref: '#/components/schemas/PSKSecret'

      X509CertificateCredentials:
         additionalProperties: false
         allOf:
            - $ref: '#/components/schemas/CommonCredentials'
            - type: object
              additionalProperties: false
              properties:
                 "secrets":
                    type: array
                    items:
                       $ref: '#/components/schemas/X509CertificateSecret'

      CommonSecret:
         type: object
         additionalProperties: false
         properties:
            "id":
               type: string
               description: The device registry can assign an identity to the secret.
                            This value can be used to update secrets based on their metadata.
            "enabled":
               type: boolean
               default: true
            "not-before":
               type: string
               format: date-time
            "not-after":
               type: string
               format: date-time
            "comment":
               type: string

      X509CertificateSecret:
         additionalProperties: false
         allOf:
            - $ref: '#/components/schemas/CommonSecret'

      PasswordSecret:
         description: |
                      Password based secret definition <br>
                      __NOTE__: Defining password secrets with user provided password hash, function and salt is deprecated and will be removed
                      in the upcoming versions. You should use `pwd-plain` property only going forward.
         additionalProperties: false
         allOf:
            - $ref: '#/components/schemas/CommonSecret'
            - type: object
              additionalProperties: false
              properties:
                 "hash-function":
                    type: string
                    example: bcrypt
                    description: __DEPRECATED!__ The name of the hash function used to create the password hash (defined in `pwd-hash` property).
                                 If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry.
                                 This property should be empty when returning passwords from the device registry using only secret metadata.
                                 In this case the id field must be set instead.
                    deprecated: true
                 "pwd-hash":
                    type: string
                    format: byte
                    description: __DEPRECATED!__ The password hash created using the `hash-function` and optional `salt` values.
                                 If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry.
                                 This property should be empty when returning passwords from the device registry using only secret metadata.
                                 In this case the id field must be set instead.
                    deprecated: true
                 "salt":
                    type: string
                    format: byte
                    description: __DEPRECATED!__ The Base64 encoding of the salt used in the password hash (defined in the `pwd-hash` property).
                                 If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry.
                                 This property should be empty when returning passwords from the device registry using only secret metadata.
                                 In this case the id field must be set instead.
                    deprecated: true
                 "pwd-plain":
                    type: string
                    format: byte
                    description: The clear text value of the password to be hashed by the device registry.
                                 If this property is specified, the device registry will ignore user-provided hash properties (`hash-function`, `pwd-hash` and `salt`).
                                 This property should never be stored by the device registry.
                                 This property should be empty when returning passwords from the device registry.

      PSKSecret:
         additionalProperties: false
         allOf:
            - $ref: '#/components/schemas/CommonSecret'
            - type: object
              additionalProperties: false
              required:
                 - key
              properties:
                 "key":
                    type: string
                    format: byte

   parameters:

      resourceVersion:
         name: If-Match
         in: header
         description: The expected resource version
         required: false
         schema:
            type: string

      tenantId:
         name: tenantId
         in: path
         description: The ID of the tenant
         required: true
         schema:
            type: string
         example: DEFAULT_TENANT

      deviceId:
         name: deviceId
         in: path
         description: The ID of the device
         required: true
         schema:
            type: string
         example: 4711

      authId:
         name: authId
         in: path
         description: The authentication ID of the device
         required: true
         schema:
            type: string
         example: sensor1

      type:
         name: type
         in: path
         description: The credentials type
         required: true
         schema:
            type: string
         example: sha-256

   responses:

      Unauthorized:
         description: Authentication credentials are required, but missing.
         headers:
            "WWW-Authenticate":
               schema:
                  type: string

      Created:
         description: Object created.
         headers:
            Location:
               description: URL to the resource
               schema:
                  type: string
                  format: uri
            ETag:
               description: The new version of the resource
               schema:
                  type: string
         content:
            application/json:
               schema:
                  type: object
                  additionalProperties: false
                  required:
                     - id
                  properties:
                     id:
                        type: string
                        description: The ID of the created object

      Updated:
         description: Object updated.
         headers:
            ETag:
               description: The new version of the resource
               schema:
                  type: string

      Deleted:
         description: Object deleted.

      NotFound:
         description: |
            Object not found. This may also be returned for some operations
            if the user misses read access for the object.
         content:
            application/json:
               schema:
                  $ref: '#/components/schemas/Error'

      NotAllowed:
         description: |
            Operation not allowed. If the user does not have read access
            for this object, then `404` will be returned instead.
         content:
            application/json:
               schema:
                  $ref: '#/components/schemas/Error'

      MalformedRequest:
         description: Malformed request
         content:
            application/json:
               schema:
                  $ref: '#/components/schemas/Error'

      AlreadyExists:
         description: |
            Object already exists. If the user has no read access for
            the existing object, then `403` should be returned instead.
         content:
            application/json:
               schema:
                  $ref: '#/components/schemas/Error'

      ResourceVersionMismatch:
         description: |
            Expected resource version does not match current.
            This can only happen when the request header `If-Match`
            was set.
         content:
            application/json:
               schema:
                  $ref: '#/components/schemas/Error'

   securitySchemes:

      BearerAuth:
         type: http
         scheme: bearer

      BasicAuth:
         type: http
         scheme: basic

   examples:
      HashedPasswordExample:
         value:
            [{
                auth-id: sensor1,
                type: hashed-password,
                secrets: [{
                             "not-after": "2027-12-24T19:00:00Z",
                             "pwd-hash": "AQIDBAUGBwg=",
                             "salt": "Mq7wFw==",
                             "hash-function": "sha-512"
                          }]
             }]

      PlainPasswordExample:
         value:
           [{
               auth-id: sensor1,
               type: hashed-password,
               secrets: [{
                  "id": "349556ea-4902-47c7-beb0-1009ab693fb4",
                  "not-after": "2027-12-24T19:00:00Z",
                  "pwd-plain": "hono-secret"
               }]
            }]
      MetaPasswordExample:
         value:
           [{
               auth-id: sensor1,
               type: hashed-password,
               secrets: [{
                  "id": "349556ea-4902-47c7-beb0-1009ab693fb4",
                  "not-after": "2027-12-24T19:00:00Z",
                  "pwd-plain": "",
                  "pwd-hash": "",
                  "salt": "",
                  "hash-function": ""
               }]
            }]