Encrypted Files

Use the Encrypted Files resource to upload protected documents for DID registration and verification.

An Encrypted File is a temporary uploaded document that can be linked to a Proof, a Permanent Supporting Document, or an Address Verification. The API returns metadata such as the file description and expires_at value. It does not return the original document content through the Encrypted Files retrieval endpoints.

Before uploading a document, retrieve the current DIDWW RSA public keys and encrypt the file. Submit the matching encryption fingerprint with the encrypted file so DIDWW can validate which key was used.

Note

For the complete registration workflow, see Regulation Resources. For an end-to-end purchasing and verification example, see Buy a DID Number That Requires Verification.

Upload requirements

• Retrieve the current key through Get Public Keys before encrypting the document.

• Follow Encryption Details to encrypt the file and calculate the required fingerprint. Browser-side encryption using @didww/encrypt is the recommended approach. Server-side examples are also available for supported SDKs.

• Send the upload as multipart/form-data with encrypted_files[encryption_fingerprint] and encrypted_files[file].

• encrypted_files[description] is optional.

• The accepted file formats are .pdf, .jpg, and .png.

• Upload one file per request. Each file must not exceed 20 MB.

• An uploaded Encrypted File expires after 24 hours. Link its ID to the required resource before the expires_at time.

• Legacy batch parameters such as encrypted_files[items][][file] are not supported in API version 2026-04-16 and return 400 Bad Request.

• An outdated encryption fingerprint returns 422 Unprocessable Entity. Retrieve the current public keys, encrypt the file again, and retry with the new fingerprint.

Endpoints

Action	Method	Endpoint
Retrieve public keys	GET	/v3/public_keys
Retrieve all Encrypted Files	GET	/v3/encrypted_files
Retrieve Encrypted File	GET	/v3/encrypted_files/{id}
Create Encrypted File	POST	/v3/encrypted_files
Delete Encrypted File	DELETE	/v3/encrypted_files/{id}

Retrieve public keys

Retrieves the DIDWW RSA public keys used to encrypt documents.

Use a current key to encrypt the source document and calculate the fingerprint supplied with the upload. Retrieving the keys immediately before encryption helps avoid an outdated fingerprint error.

See Get Public Keys and Encryption Details.

GET /v3/public_keys

Retrieve all Encrypted Files

Retrieves metadata for all Encrypted Files associated with the account.

Use this endpoint to find uploaded file IDs and check their descriptions or expiration times. Results can be sorted by description or expires_at.

See Retrieve All Encrypted Files.

GET /v3/encrypted_files

Retrieve Encrypted File

Retrieves the metadata for a specific Encrypted File by its unique ID.

Use this endpoint to check the file description and expires_at time before linking the file to another regulation resource.

See Retrieve Encrypted File.

GET /v3/encrypted_files/{id}

Create Encrypted File

Uploads one encrypted document to the account.

Use multipart/form-data and provide the encrypted file and current encryption fingerprint. The successful JSON:API response returns the Encrypted File ID and its expires_at time. Use that ID within 24 hours to create a Proof or Permanent Supporting Document, or to attach a one-time document to an Address Verification.

See Create Encrypted File.

POST /v3/encrypted_files

Delete Encrypted File

Deletes an Encrypted File by its unique ID.

Use this endpoint to remove an uploaded file that is no longer needed.

See Delete Encrypted File.

DELETE /v3/encrypted_files/{id}

Data reference

See Encrypted Files Object for the returned metadata and upload fields. See Encryption Details for the encryption and fingerprint process.

How an uploaded file is used

Target resource	Use
Proof	Link the Encrypted File with an accepted Proof Type and the relevant Identity or Address.
Permanent Supporting Document	Link one or more Encrypted Files with a permanent Supporting Document Template and an Identity.
Address Verification	Pass the Encrypted File ID in onetime_files when the Address Requirement calls for a one-time supporting document.

Common Encrypted File use cases

Use case	Description
Encrypt a registration document	Retrieve a current public key and encrypt a supported source file before upload.
Upload identity evidence	Upload a passport, identification document, or other accepted evidence before creating a Proof linked to an Identity.
Upload address evidence	Upload a bill, receipt, or other accepted evidence before creating a Proof linked to an Address.
Upload a completed regulatory form	Upload a completed Supporting Document Template for permanent or one-time use.
Check expiration	Retrieve file metadata and confirm that the file can be linked before it expires.
Remove an unused upload	Delete an Encrypted File that should not be used in the registration workflow.

Related resources

• Public Keys — Retrieve the RSA keys required before encrypting a document.

• Encryption Details — Implement file encryption and fingerprint calculation.

• Proofs — Link an uploaded file as accepted evidence for an Identity or Address.

• Supporting Document Templates — Retrieve regulatory forms that must be completed and uploaded.

• Permanent Supporting Documents — Link reusable completed forms to an Identity.

• Address Verifications — Submit one-time encrypted files with a verification task.