diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index 3eb312728..59337e007 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -51,29 +51,30 @@ Tokens can be used to save arbitrary structured data on the Backbone, which is e A Token has the following properties: -| Name | Type | Description | Remarks | -| ------------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | -| createdBy | `string` | {% include descr_createdBy class="Token" %} | | -| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | -| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone | -| createdAt | `string` | {% include descr_createdAt class="Token" %} | | -| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | | -| forIdentity | `string` \| `undefined` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the Token from the Backbone. | -| passwordProtection | [`object for password protection of Token`](#object-for-password-protection-of-token) \| `undefined` | Information about whether or not the Token is protected by a password or pin. | | -| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally | -| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. | - -### Object for Password Protection of Token - -A [Token](#token) can be protected by a password to ensure that it is protected from unauthorized access. -In order for an Identity to [load the Token]({% link _docs_use-cases/use-case-transport-load-token-created-by-others.md %}), it must enter the correct password. -Information about the password protection of a Token is recorded within its optional `passwordProtection` property. - -| Name | Type | Description | Remarks | -| ------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| password | `string` | The password of the Token. | | -| passwordIsPin | `true` \| `undefined` | If the password of the Token consists of 4 to 16 digits, the value of the `passwordIsPin` property can be set to `true`. In this case, the password is interpreted as a pin and a corresponding input field is displayed in the UI of the App when the pin needs to be entered. However, if the value is `undefined`, a regular input field for entering the password is displayed regardless of whether the password could also be interpreted as a pin. | | +| Name | Type | Description | Remarks | +| ------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | +| createdBy | `string` | {% include descr_createdBy class="Token" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | +| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone | +| createdAt | `string` | {% include descr_createdAt class="Token" %} | | +| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | | +| forIdentity | `string` \| `undefined` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the Token from the Backbone. | +| passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the Token is protected by a password or pin. | | +| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally | +| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. | + +### PasswordProtection + +A [Token](#token) or [RelationshipTemplate can be protected by a password]({% link _docs_integrate/establish-relationships.md %}#password-protection-of-a-relationshiptemplate) to ensure that it is protected from unauthorized access. +In order for a peer to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) to the creator of a password protected [RelationshipTemplate](#relationshiptemplate), it must enter the correct password when [loading the RelationshipTemplate]({% link _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md %}). +Similarly, in order for an Identity to [load a Token]({% link _docs_use-cases/use-case-transport-load-token-created-by-others.md %}) that is password protected, it must enter the correct password. +Information about the password protection of a Token or a RelationshipTemplate is recorded within its optional `passwordProtection` property. + +| Name | Type | Description | Remarks | +| ------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| password | `string` | The password of the Token or the RelationshipTemplate. | | +| passwordIsPin | `true` \| `undefined` | If the password consists of 4 to 16 digits, the value of the `passwordIsPin` property can be set to `true`. In this case, the password is interpreted as a pin and a corresponding input field is displayed in the UI of the App when the pin needs to be entered. However, if the value is `undefined`, a regular input field for entering the password is displayed regardless of whether the password could also be interpreted as a pin. | | ## RelationshipTemplate @@ -93,20 +94,9 @@ A RelationshipTemplate serves two purposes: | expiresAt | `string` | {% include descr_expiresAt class="RelationshipTemplate" %} | will be encrypted before sent to the Backbone | | maxNumberOfAllocations | `number` \| `undefined` | Can be set to limit the number of allocations of this RelationshipTemplate. A RelationshipTemplate is allocated by another Identity when it is first retrieved by it from the Backbone. After this value is reached, the Backbone rejects each request of any new Identity that wants to retrieve it. Identities that already allocated it will still be able to retrieve it. | | | forIdentity | `string` \| `undefined` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the RelationshipTemplate from the Backbone. | | -| passwordProtection | [`object for password protection of RelationshipTemplate`](#object-for-password-protection-of-relationshiptemplate) \| `undefined` | Information about whether or not the RelationshipTemplate is protected by a password or pin. | | +| passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the RelationshipTemplate is protected by a password or pin. | | | truncatedReference | `string` | {% include descr_truncatedReference class="RelationshipTemplate" %} | saved only locally | -### Object for Password Protection of RelationshipTemplate - -A [RelationshipTemplate can be protected by a password]({% link _docs_integrate/establish-relationships.md %}#password-protection-of-a-relationshiptemplate) to ensure that it is protected from unauthorized access. -In order for a peer to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) to the creator of the password protected RelationshipTemplate, it must enter the correct password when [loading the RelationshipTemplate]({% link _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md %}). -Information about the password protection of a [RelationshipTemplate](#relationshiptemplate) is recorded within its optional `passwordProtection` property. - -| Name | Type | Description | Remarks | -| ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -| password | `string` | The password of the RelationshipTemplate. | | -| passwordIsPin | `true` \| `undefined` | If the password of the RelationshipTemplate consists of 4 to 16 digits, the value of the `passwordIsPin` property can be set to `true`. In this case, the password is interpreted as a pin and a corresponding input field is displayed in the UI of the App when the pin needs to be entered. However, if the value is `undefined`, a regular input field for entering the password is displayed regardless of whether the password could also be interpreted as a pin. | | - ## Relationship A Relationship between two Identities is the prerequisite for them to exchange Messages. If there is no Relationship, the Backbone blocks all Messages that are tried to be sent. This ensures that you only receive Messages from Identities you know, so you are protected from any harmful Messages like spam or phishing mails. diff --git a/_docs_use-cases/use-case-transport-create-device-onboarding-token.md b/_docs_use-cases/use-case-transport-create-device-onboarding-token.md index d23d15d65..0ea824687 100644 --- a/_docs_use-cases/use-case-transport-create-device-onboarding-token.md +++ b/_docs_use-cases/use-case-transport-create-device-onboarding-token.md @@ -47,7 +47,7 @@ This use case retrieves the [Token]({% link _docs_integrate/data-model-overview. - `id` of the Device. - `expiresAt` is the ISODateTime the Token expires at. -- `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. ## On Success diff --git a/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md index bdce73ea1..17922d955 100644 --- a/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md @@ -52,7 +52,7 @@ A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relat - `content` describes the structure of the RelationshipTemplate. If an enmeshed App user shall receive this RelationshipTemplate, a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) is required as structure, otherwise an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) containing any data can be used. - `maxNumberOfAllocations` is the number of times the RelationshipTemplate can be accessed by different Identities to initiate a Relationship. The Backbone returns an error, if one accesses a RelationshipTemplate with no allocations left. Accessing the same RelationshipTemplate with the same Identity multiple times doesn't affect the number of allocations. The allocation counts, even if the Identity does not accept the RelationshipTemplate by discarding it. - `forIdentity` can be set to an enmeshed address. If set, only the Identity with that `address` can access the RelationshipTemplate. -- `passwordProtection` can be specified as an [object for password protection of a RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-relationshiptemplate). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the RelationshipTemplate can access it. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a RelationshipTemplate. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the RelationshipTemplate can access it. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. ## On Success diff --git a/_docs_use-cases/use-case-transport-create-own-token.md b/_docs_use-cases/use-case-transport-create-own-token.md index 1f4a85806..0a5c47ce6 100644 --- a/_docs_use-cases/use-case-transport-create-own-token.md +++ b/_docs_use-cases/use-case-transport-create-own-token.md @@ -50,7 +50,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that - `expiresAt` is the ISODateTime the Token expires at. - `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. - `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. -- `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. ## On Success diff --git a/_docs_use-cases/use-case-transport-create-token-for-file.md b/_docs_use-cases/use-case-transport-create-token-for-file.md index 18c790fd3..1ec6681ce 100644 --- a/_docs_use-cases/use-case-transport-create-token-for-file.md +++ b/_docs_use-cases/use-case-transport-create-token-for-file.md @@ -50,7 +50,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a - Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at. - Optionally, `ephemeral` can be specified, which indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and don't need to be stored. - Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone. -- Optionally, `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. +- Optionally, `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. ## On Success diff --git a/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md index 9f9b29f7b..dbe3ecfc0 100644 --- a/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md @@ -52,7 +52,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a - `expiresAt` is the ISODateTime the Token expires at. - `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. - `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. If the RelationshipTemplate is already personalized via its `forIdentity` property, the Token created from it must have the same personalization. -- `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. If the RelationshipTemplate is already password protected via its `passwordProtection` property, the Token created from it must have the same password protection. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. If the RelationshipTemplate is already password protected via its `passwordProtection` property, the Token created from it must have the same password protection. ## On Success diff --git a/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md b/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md index a92a1dc4d..d7c9c55f5 100644 --- a/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md +++ b/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md @@ -49,7 +49,7 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md % - `fileId` is the `id` of the File the Token and its QR code should be created for. - Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at. - Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone. -- Optionally, `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. +- Optionally, `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. ## On Success diff --git a/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md index df6f4a67d..96875bb84 100644 --- a/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md @@ -49,7 +49,7 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md % - `templateId` is the `id` of the RelationshipTemplate the Token and its QR code should be created for. - `expiresAt` is the ISODateTime the Token expires at. - `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. If the RelationshipTemplate is already personalized via its `forIdentity` property, the Token created from it must have the same personalization. -- `passwordProtection` can be specified as an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. If the RelationshipTemplate is already password protected via its `passwordProtection` property, the Token created from it must have the same password protection. +- `passwordProtection` can be specified as an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. If set, only the Identities that know the password specified within the `passwordProtection.password` property of the Token can load it from the Backbone. In addition, the optional property `passwordProtection.passwordIsPin` can be used to configure the UI of the App in case the password is a pin. If the RelationshipTemplate is already password protected via its `passwordProtection` property, the Token created from it must have the same password protection. ## On Success diff --git a/_docs_use-cases/use-case-transport-query-relationshiptemplates.md b/_docs_use-cases/use-case-transport-query-relationshiptemplates.md index b5b7438a1..0832ff445 100644 --- a/_docs_use-cases/use-case-transport-query-relationshiptemplates.md +++ b/_docs_use-cases/use-case-transport-query-relationshiptemplates.md @@ -57,7 +57,7 @@ All parameters are optional. If no parameter is given, all RelationshipTemplates - `createdByDevice` is the `id` of the Device that created the RelationshipTemplate. - `maxNumberOfAllocations` is the number of times the RelationshipTemplate can be accessed by different Identities to initiate a Relationship. The Backbone returns an error if one accesses a RelationshipTemplate with no allocations left. Accessing the same RelationshipTemplate with the same Identity multiple times doesn't affect the number of allocations. The allocation counts, even if the Identity does not accept the RelationshipTemplate by discarding it. - `forIdentity` is the enmeshed `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) for which the RelationshipTemplate is intended. -- `passwordProtection` is an [object for password protection of a RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-relationshiptemplate). +- `passwordProtection` is an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a RelationshipTemplate. ## On Success diff --git a/_docs_use-cases/use-case-transport-query-tokens-by-parameters.md b/_docs_use-cases/use-case-transport-query-tokens-by-parameters.md index 05815f9be..0aba7fd5a 100644 --- a/_docs_use-cases/use-case-transport-query-tokens-by-parameters.md +++ b/_docs_use-cases/use-case-transport-query-tokens-by-parameters.md @@ -50,7 +50,7 @@ This use case queries [Tokens]({% link _docs_integrate/data-model-overview.md %} - `createdByDevice` is the `id` of the Device that created the Token. - `expiresAt` is the ISODateTime the Token expires. - `forIdentity` is the enmeshed `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) for which the Token is intended. -- `passwordProtection` is an [object for password protection of a Token]({% link _docs_integrate/data-model-overview.md %}#object-for-password-protection-of-token). +- `passwordProtection` is an object for [PasswordProtection]({% link _docs_integrate/data-model-overview.md %}#passwordprotection) of a Token. ## On Success