Personalization of Tokens and RelationshipTemplates

_docs_integrate/data-model-overview.md

@@ -59,6 +59,7 @@ A Token has the following properties:
 | 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`  | Can be set to an enmeshed Address. If set, then only the Identity with that Address can retrieve the Token from the Backbone.                                               |
 | 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. |
 
@@ -79,6 +80,7 @@ A RelationshipTemplate serves two purposes:
 | content                | [`RelationshipTemplateContent`](#relationshiptemplatecontent) \| [`ArbitraryRelationshipTemplateContent`](#arbitraryrelationshiptemplatecontent) | The content of the RelationshipTemplate. If it is intended for a User of the enmeshed App, `RelationshipTemplateContent` has to be used. Otherwise, an `ArbitraryRelationshipTemplateContent` can also be used, which can be filled with anything and serves as a fallback if the `RelationshipTemplateContent` is not sufficient.                                            |                                               |
 | 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`                                                                                                                                         | Can be set to an enmeshed Address. If set, then only the Identity with that Address can retrieve the RelationshipTemplate from the Backbone.                                                                                                                                                                                                                                  |                                               |
 | truncatedReference     | `string`                                                                                                                                         | {% include descr_truncatedReference class="RelationshipTemplate" %}                                                                                                                                                                                                                                                                                                           | saved only locally                            |
 
 ## Relationship

_docs_integrate/establish-relationships.md

@@ -81,6 +81,20 @@ If you have successfully created the [RelationshipTemplate]({% link _docs_integr
 
 {% include copy-notice description="Save the `id` of the RelationshipTemplate so that you can refer to it and make it available to other Identities later. For the same reason, save the value of the property `truncatedReference`." %}
 
+### Personalize the RelationshipTemplate
+
+If the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is only for creating a Relationship with a single known Identity, you can set that Identity's Address in the RelationshipTemplate:
+
+```jsonc
+{
+  ...,
+  "content": {...},
+  "forIdentity": "<Address that the RelationshipTemplate is intended for>"
+}
+```
+
+Only that Identity will be able to continue with establishing a Relationship. This also protects sensitive data of that Identity contained in the RelationshipTemplate from outside access.
+
 ## Make the RelationshipTemplate Available
 
 For an Identity to initiate a Relationship with the templator, it must use a valid [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) which is owned by the templator. Depending on whether the Identity is a Connector or an App user, a different approach must be used to make the RelationshipTemplate available to the Identity:

_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md

@@ -51,6 +51,7 @@ A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relat
 - `expiresAt` is the ISODateTime the RelationshipTemplate expires at. This should be set as small as possible and cannot be in the past.
 - `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.
 
 ## On Success
 

_docs_use-cases/use-case-transport-create-own-token.md

@@ -49,6 +49,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that
 - `content` an arbitrary JSON structure of the data to share via the Token.
 - `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 with that Address can load the Token from the Backbone.
 
 ## On Success
 

_docs_use-cases/use-case-transport-create-token-for-file.md

@@ -49,6 +49,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a
 - `fileId` is the `id` of the File the Token should be created for.
 - 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 that will be able to load the Token from the Backbone.
 
 ## On Success
 

_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md

@@ -48,9 +48,10 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a
 
 ## Parameters
 
-- `fileId` is the id of the File the Token should be created for.
+- `templateId` is the id of the RelationshipTemplate the Token should be created for.
 - `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 with that Address can load the Token from the Backbone.
 
 ## On Success
 

_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md

@@ -48,6 +48,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 that will be able to load the Token from the Backbone.
 
 ## On Success
 

_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md

@@ -1,7 +1,7 @@
 ---
 # Start automatic generation
 permalink: use-case-transport-create-token-qr-code-for-own-relationshiptemplate
-published: false
+published: true
 title: "Create Token QR code for own RelationshipTemplate"
 type: use-case
 toc: true
@@ -18,8 +18,8 @@ properties:
   - feature category: Consent required before any data is shared
   - tech category: RelationshipTemplates
   - status: DONE
-  - documentation status:
-  - comments:
+  - documentation status: DONE
+  - comments: "Accept: image/png"
   - actor: Identity
   - trigger:
   - precondition:
@@ -29,10 +29,32 @@ properties:
   - size: n/a
   - created_at:
   - changed_at:
-  - api_route_regex:
+  - api_route_regex: POST /api/v2/RelationshipTemplates/Own/{id}/Token
   - published: default
   - link: use-case-transport-create-token-qr-code-for-own-relationshiptemplate
 require:
 required_by:
+api_route_regex: ^POST /api/v2/RelationshipTemplates/Own/{id}/Token$
 # End automatic generation
 ---
+
+{{properties.description}}
+
+{% include properties_list.html %}
+
+Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md %}#token) of a given [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate)
+
+## Parameters
+
+- `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 with that Address can load the Token from the Backbone.
+
+## On Success
+
+- Returns the created QR code encoded as Base64.
+
+## On Failure
+
+- `templateId` does not resolve to a RelationshipTemplate.
+- `expiresAt` lies in the past

_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md

@@ -44,7 +44,7 @@ api_route_regex: ^POST /api/v2/RelationshipTemplates/Peer$
 
 {% include properties_list.html %}
 
-This use case loads a peer's [RelatonshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) from the Backbone by a given reference to the RelationshipTemplate.
+This use case loads a peer's [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) from the Backbone by a given reference to the RelationshipTemplate.
 
 ## Parameters
 
@@ -65,3 +65,4 @@ There are two different options to use this use case, depending on the actual in
 - The RelationshipTemplate does not exist.
 - The RelationshipTemplate is expired.
 - The `maxNumberOfAllocations` of the RelationshipTemplate are depleted.
+- The RelationshipTemplate is personalized to a different Identity (via the property `forIdentity` of the RelationshipTemplate)

_docs_use-cases/use-case-transport-load-token-created-by-others.md

@@ -60,3 +60,4 @@ You can execute this use case if you know the `truncatedReference` of the peer's
 - The parameters are malformed.
 - The Token does not exist.
 - The Token is expired.
+- The Token is personalized to a different Identity (via the property `forIdentity` of the Token)