Request Items

All the RequestItems listed below inherit from the RequestItem and are therefore sharing its properties.

AuthenticationRequestItem

With this item the sender can request the peer for an authentication in a business context for a certain purpose. The peer can then decide to authenticate or not. This authentication is mostly short-lived and limited in time.

Examples

• Authentication for a login to a website
• Authentication for opening a door

Properties

Name	Type	Description
@type	"AuthenticationRequestItem"	Specifies the type of the RequestItem for internal processing.

Response Parameters

Item Properties

• To accept this RequestItem an AcceptResponseItem will be transferred.
• To reject this RequestItem a RejectResponseItem will be transferred.
• In case of an error an ErrorResponseItem will be transferred.

Parameters

• To accept this RequestItem you can send { "accept": true } as parameters.
• To reject this RequestItem you can send { "accept": false } as parameters.

ConsentRequestItem

With the ConsentRequestItem it is possible to request a consent of the peer to an arbitrary text and thus reach agreement on a certain non machine-processable context.

To request an accept/reject decision from a peer to a free text, the ConsentRequestItem is used.

Please do not use the ConsentRequestItem to submit tons of text to the peer Identity. It is meant to be a short consent or summary the user agrees to. Please move longer text to external websites. The ConsentRequestItem is also not meant for contractual agreements.

Examples

• “I hereby confirm that I have read the privacy terms of this cloud service and agree to them.”
• “The provided EULA has been read and agreed to.”
• “Yes, I have backed up all of my data of this PC and you can wipe it.”
• “I opt in to the newsletter.”

Properties

Name	Type	Description
@type	"ConsentRequestItem"	Specifies the type of the RequestItem for internal processing.
consent	string	The textual consent the user needs to give. This is different to the title and description of the RequestItem, as the consent would be the actual statement the user agrees to.
link	string | undefined	A link to a website which contains more information, like the EULA or privacy terms.

Response Parameters

Item Properties

• To accept this RequestItem an AcceptResponseItem will be transferred.
• To reject this RequestItem a RejectResponseItem will be transferred.
• In case of an error an ErrorResponseItem will be transferred.

Parameters

• To accept this RequestItem you can send { "accept": true } as parameters.
• To reject this RequestItem you can send { "accept": false } as parameters.

CreateAttributeRequestItem

If you want to create Identity- or RelationshipAttributes for the peer, the CreateAttributeRequestItem can be used. Please have a look at the ProposeAttributeRequestItem if the peer should be able to overwrite the Attribute.

To create an Attribute with a fixed value defined by the sender, an Identity uses the CreateAttributeRequestItem. A fixed value in this case means, that the recipient is not allowed to change the value when accepting the request.

Examples

• Share the corporate E-Mail Address of the peer to the peer
• Send a certificate of the peer to the peer, so that the peer is able to easily share it
• Create a RelationshipAttribute for the peer

Properties

Name	Type	Description
@type	"CreateAttributeRequestItem"	Specifies the type of the RequestItem for internal processing.
attribute	IdentityAttribute | RelationshipAttribute	The IdentityAttribute or RelationshipAttribute to create for the peer within the Identity of the peer.

Response

Item Properties

• To accept this RequestItem a CreateAttributeAcceptResponseItem will be transferred.

  Name	Type	Description
  @type	"CreateAttributeAcceptResponseItem"	The type of the ResponseItem.
  attributeId	string	The id of the created Attribute.

• To reject this RequestItem a RejectResponseItem will be transferred.
• In case of an error an ErrorResponseItem will be transferred.

Parameters

• To accept this RequestItem you can send { "accept": true } as parameters.
• To reject this RequestItem you can send { "accept": false } as parameters.

Combinations and usage scenarios

Attribute Type	Attribute Owner	Possible?	Automation	Examples/Reason
Identity	Sender	N	N/A	Use ShareAttributeRequestItem instead.
Identity	Recipient	Y	USER_DECISION	University sends student his certificate (Propose would be inappropriate in this case, because the student should not be able to return his own value)
Identity	<empty>	Y	USER_DECISION	An empty owner defaults to an Attribute with owner=<recipient>. This is needed for Requests inside of Relationship Templates, since you don’t know the Enmeshed Address of your peer before the Relationship is established.
Relationship	Sender	Y	AUTO_ACCEPT	Company sends new customer his customer number.
Relationship	Recipient	Y	USER_DECISION	With this combination the sender asks the recipient for the one-time permission to write a Relationship Attribute once AND the sender defined a value which can either be accepted and stored, or rejected. Thus, the user cannot change the value by itself.
Relationship	<empty>	Y	USER_DECISION	An empty owner defaults to an Attribute with owner=<recipient>. This is needed for Requests inside of Relationship Templates, since you don’t know the Enmeshed Address of your peer before the Relationship is established.

FreeTextRequestItem

With the FreeTextRequestItem it is possible to send a free text to the peer. The peer itself can accept this with a free text as well.

Properties

Name	Type	Description
@type	"FreeTextRequestItem"	Specifies the type of the RequestItem for internal processing.
freeText	string	The free text you want to send to the peer.

Response Parameters

Item Properties

• To accept this RequestItem a FreeTextAcceptResponseItem will be transferred.

  Name	Type	Description
  @type	"FreeTextAcceptResponseItem"	The type of the ResponseItem.
  freeText	string	The free text that is used to answer the RequestItem.

• To reject this RequestItem a RejectResponseItem will be transferred.
• In case of an error an ErrorResponseItem will be transferred.

Parameters

• To accept this RequestItem you can send the following parameters.

  Name	Type	Description
  accept	true
  freeText	string	The free text you want to send to the peer.

• To reject this RequestItem you can send { "accept": false } as parameters.

ProposeAttributeRequestItem

The ProposeAttributeRequestItem is a combination of ReadAttributeRequestItem and CreateAttributeRequestItem. The sender would like to receive a correct Attribute from the peer, thinks it has a possible value but the peer might overrule this value with an existing or new one.

To create an Attribute with a value proposed by the sender, an Identity uses the ProposeAttributeRequestItem. A proposed value in this case means, that the recipient is allowed to change the value if accepting the request.

Examples

• Onboard an existing customer to Enmeshed and propose the known private Attributes, like its name or address.
• Ask the user if a newsletter would be of interest and propose the opt-in. This could be stored as a RelationshipAttribute with owner = recipient and could then be changed by the recipient at will.

Properties

Name	Type	Description
@type	"ProposeAttributeRequestItem"	Specifies the type of the RequestItem for internal processing.
attribute	IdentityAttribute | RelationshipAttribute	The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute.
query	IdentityAttributeQuery | RelationshipAttributeQuery | ThirdPartyRelationshipAttributeQuery	The structured query of the Attribute the sender would like to receive.

Response

Item Properties

• To accept this RequestItem a ProposeAttributeAcceptResponseItem will be transferred.

  Name	Type	Description
  @type	"ProposeAttributeAcceptResponseItem"	The type of the ResponseItem.
  attributeId	string	The id of the created Attribute.
  attribute	IdentityAttribute | RelationshipAttribute	The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute. The owner of the Attribute which is proposed can only be the recipient Identity.

• To reject this RequestItem a RejectResponseItem will be transferred.
• In case of an error an ErrorResponseItem will be transferred.

Parameters

• To accept this RequestItem you can send the following parameters.

  • If you want to create a new Attribute.

    Name	Type	Description
    attribute	IdentityAttribute | RelationshipAttribute	The IdentityAttribute or RelationshipAttribute that shall be created.

  • If you want to use the proposed Attribute.

    Name	Type	Description
    attribute	IdentityAttribute | RelationshipAttribute	The IdentityAttribute or RelationshipAttribute that was provided in the RequestItem.

  • If you want to use an existing Attribute.

    Name	Type	Description
    existingAttributeId	string	The id of the Attribute to send.

• To reject this RequestItem you can send { "accept": false } as parameters.

Combinations and usage scenarios

Attribute Type	Attribute Owner	Possible?	Automation	Examples/Reason
Identity	Sender	N	N/A	It makes no sense to propose own Attributes, use ShareAttributeRequestItem instead.
Identity	Recipient	Y	USER_DECISION	Company sends name and address to new customer during its onboarding process.
Relationship	Sender	Y	USER_DECISION	With this combination the sender gives the recipient the one-time permission to write a Relationship Attribute once AND the sender proposes a value which might make sense as a default. Example: Electricity provider asks new customer for the electricity meter number and proposes a known number
Relationship	Recipient	Y	USER_DECISION	With this combination the sender asks the recipient for the one-time permission to write a Relationship Attribute once AND the sender proposes a value which might make sense as a default. Example: Asking for a newsletter subscription

ReadAttributeRequestItem

If you want to query an Identity’s Attributes this is done with the ReadAttributeRequestItem.

To query Attributes which are not known to the sender, an Identity uses the ReadAttributeRequestItem.

Examples

• Optional query of the BirthDate, to congratulate on birthdays
• Required query of the Age, to check if alcohol may be bought
• Required query of the StreetAddress, to send an invoice to the recipient

Properties

Name	Type	Description
@type	"ReadAttributeRequestItem"	Specifies the type of the RequestItem for internal processing.
query	IdentityAttributeQuery | RelationshipAttributeQuery | ThirdPartyRelationshipAttributeQuery	The structured query of the Attribute the sender would like to receive.

Response

Item Properties

• To accept this RequestItem a ReadAttributeAcceptResponseItem will be transferred.

  Name	Type	Description
  @type	"ReadAttributeAcceptResponseItem"	The type of the ResponseItem.
  attributeId	string	The id of the returned Attribute.
  attribute	IdentityAttribute | RelationshipAttribute	The IdentityAttribute or RelationshipAttribute that will be shared to the peer.

• To reject this RequestItem a RejectResponseItem will be transferred.
• In case of an error an ErrorResponseItem will be transferred.

Parameters

• To accept this RequestItem you can send the following parameters.

  • If you want to use an existing Attribute.

    Name	Type	Description
    existingAttributeId	string	The id of the Attribute to send.

  • If you want to create a new Attribute.

    Name	Type	Description
    attribute	IdentityAttribute | RelationshipAttribute	The IdentityAttribute or RelationshipAttribute that shall be created.

• To reject this RequestItem you can send { "accept": false } as parameters.

Combinations and usage scenarios

Attribute Type	Attribute Owner	Third Party	Possible?	Automation	Examples/Reason
Identity	Sender		N	N/A	It makes no sense to read own IdentityAttributes.
Identity	Recipient		Y	USER_DECISION	Company asks customer for its delivery address
Relationship	Sender		Y	USER_DECISION	With this combination the sender gives the recipient the one-time permission to write a Relationship Attribute once Example: Electricity provider asks new customers for electricity meter number
Relationship	Recipient		Y	USER_DECISION	With this combination the sender asks the recipient for the one-time permission to write a Relationship Attribute Example: Company asks new customer to subscribe to the newsletter and proposes the subscription as default once
Relationship	Recipient	Third Party	Y	USER DECISION / NOT ALLOWED - depending on confidentiality	With this combination the sender requests a Relationship Attribute from a Relationship between the recipient and a third party. The Attribute must be owned by the recipient Example: A Social Network asks for Facebook privacy settings of a user to get senseful defaults of its own privacy settings
Relationship	Third Party	Third Party	Y	USER DECISION / NOT ALLOWED - depending on confidentiality	With this combination the sender requests a Relationship Attribute from a Relationship between the recipient and a third party which is owned by the third party Example: An online shop asks for the Payback Customer Id of a user to book the order on his account

ShareAttributeRequestItem

If you want to share the own DisplayName and possibly other Attributes this is done with the ShareAttributeRequestItem.

To share own IdentityAttributes (owner = self) an Identity uses the ShareAttributeRequestItem. The Identity needs to create the IdentityAttribute separately before the Attribute can be shared.

Examples

• Share own DisplayName.
• Share own Address.
• Share customer number of company A with company B.

Properties

Name	Type	Description
@type	"ShareAttributeRequestItem"	Specifies the type of the RequestItem for internal processing.
attribute	IdentityAttribute | RelationshipAttribute	The IdentityAttribute or RelationshipAttribute to share. This is not the LocalAttribute but the content data structure of the Attribute. The owner of the Attribute which should be shared can only be the sender Identity.
sourceAttributeId	string	The id of the LocalAttribute which is the source of the shared Attribute. This will be used later to reference the sourceAttribute from its shared copy.

Response

Item Properties

• To accept this RequestItem a RegisterAttributeListenerAcceptResponseItem will be transferred.

  Name	Type	Description
  @type	"ShareAttributeAcceptResponseItem"	The type of the ResponseItem.
  attributeId	string	The id of the created Attribute.

• To reject this RequestItem a RejectResponseItem will be transferred.
• In case of an error an ErrorResponseItem will be transferred.

Parameters

• To accept this RequestItem you can send { "accept": true } as parameters.
• To reject this RequestItem you can send { "accept": false } as parameters.

Combinations and usage scenarios

Attribute Type	Attribute Owner	Possible?	Automation	Examples/Reason
Identity	Sender	Y	AUTO ACCEPT	Company sends new customer the address of the company
Identity	Recipient	N	N/A	It makes no sense to share the Attribute to the recipient, because he already owns it.
Identity	Third Party	N	N/A	You cannot share an Attribute of which you are not the owner.
Identity	<empty>	Y	AUTO ACCEPT	An empty owner defaults to an Attribute with owner=<sender>.
Relationship	Sender	Y	USER DECISION / NOT ALLOWED (depending on confidentiality)	A user can share own RelationshipAttributes of any Relationship to any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public). Example: Share Customer ID from Company A with Company B (User is owner of RelationshipAttribute)
Relationship	Recipient	N	N/A	It makes no sense to share the Attribute to the recipient, because he already owns it.
Relationship	Third Party	Y	USER DECISION / NOT ALLOWED (depending on confidentiality)	A user can share RelationshipAttributes of any Relationship to any other Relationship (if the confidentiality of the RelationshipAttribute is protected or public). Example: Share Customer ID from Company A with Company B (Company A is owner of RelationshipAttribute), e.g. Payback number
Relationship	<empty>	Y	AUTO ACCEPT	An empty owner defaults to an Attribute with owner=<sender>.