Sign in

v1

latestOpenAPI 3.1.02026-07-2685154311.7 KB
Entities

Get entity public encryption keys

Returns the encryption key that would be sent in webhooks for the given entity. This allows counterparties to proactively fetch encryption keys without waiting for a RequirePresentation webhook.

V1 VASP Handling: For entities using the TRNow protocol (V1 VASPs with did:ethr DIDs), this endpoint automatically returns the Gateway VASP's encryption keys instead of the entity's own keys, since V1 VASPs don't have their own encryption keys. The response includes a gatewayDID field to indicate this.

Performance Optimization: For did:web entities in the local database, encryption keys are resolved directly without Network API calls, enabling fast response times for local V2 entities.

Key Selection Priority: Uses the same priority algorithm as webhook sending:

  1. Keys ending with "#pii" (highest priority)
  2. Keys ending with "#notabene-pii"
  3. Keys with type "X25519KeyAgreementKey2019"
  4. First available key (fallback)

Response is cached via Veramo's DID resolution cache (5 minute TTL).

get/entities/{entityDID}/public-keys

Path parameters

entityDIDstring did required

Decentralized Identifier (DID)

Example:did:web:vasps.id:jxnl0411:at

The DID of the entity

Response

Successfully retrieved encryption key

entityDIDstring

The entity's DID

gatewayDIDstring

Present only for V1 VASPs - indicates Gateway VASP DID used for encryption

Example response

{
  "entityDID": "did:web:entity2.example.com",
  "encryptionKey": {
    "id": "did:web:entity2.example.com#pii",
    "type": "EcdsaSecp256r1VerificationKey2019",
    "controller": "did:web:entity2.example.com",
    "publicKeyHex": "04a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
    "publicKeyBase58": "2Abc3Def4Ghi5Jkl6Mno7Pqr8Stu9Vwx0Yza1Bcd2Efg3"
  },
  "gatewayDID": "did:web:gateway.notabene.studio"
}