Verification Relationships

A verification relationship expresses what a key previously registered in the DID can be used for. A key can have multiple simultaneous relationships, but at least one is required for the key to be operational.

addVerificationRelationship

POST /api/v1/contract/addVerificationRelationship

Associates a verification relationship with an existing key in the DID.

Body

Field	Type	Required	Description
did	string	yes	Affected DID.
name	string	yes	Name of the relationship. Typical values: assertionMethod, authentication, keyAgreement, capabilityInvocation, capabilityDelegation.
vMethodId	string	yes	ID of the verification method with which the relationship is associated. Must already exist.
notBefore	number	yes	Unix timestamp from which the relationship is valid.
notAfter	number	yes	Unix timestamp at which the relationship expires.
from	string	yes	EOA of the signing controller.

Supported name Values

name	Meaning
authentication	The key can authenticate as the DID (e.g., SIOPv2, login).
assertionMethod	The key can sign verifiable credentials and accreditations.
keyAgreement	The key can participate in key agreements (DH, ECDH-ES).
capabilityInvocation	The key can invoke delegated capabilities.
capabilityDelegation	The key can delegate capabilities.

Example

{
  "did": "did:isbe:uc:z12kVar5p6bD5WCjEJcQ18Zyt8XV",
  "name": "assertionMethod",
  "vMethodId": "WqpsDjTHnYVNvX8qx4a1FER8NgnEBS6DjLbDVrX-Fg4",
  "notBefore": 1774603242,
  "notAfter": 2090222442,
  "from": "0xAe0E493C67f75381b0954644836A3C16c79D0dFD"
}

Response

200 OK with the unsigned transaction.

Common Errors

• 400 if vMethodId does not exist in the DID (you must register it first with addVerificationMethod).
• 400 if notBefore >= notAfter.

Typical Pattern

For an issuing entity, the complete pattern for registering an operational key is:

1. addVerificationMethod with publicKeyType=JsonWebKey2020.
2. addVerificationRelationship with name=assertionMethod.

Without the second step, the key cannot be used to sign credentials.

Notes on Revoking Relationships

Currently, the API does not expose a specific endpoint to revoke an individual relationship. To invalidate a relationship:

• Revoke or expire the entire verification method with revokeVerificationMethod or expireVerificationMethod. The relationship automatically ceases to apply.
• If you only want to change the use (for example, switching from authentication to assertionMethod), add the new relationship and let the old one expire via notAfter.