| 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. |
| example: |
| subject-dn: "CN=devices,OU=iot,O=ACME" |
| public-key: "Tk9UIEEgUFVCTElDIEtFWQ==" |
| algorithm: "EC" |
| 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' |
| "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' |
| |
| 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": "" |
| }] |
| }] |
