# 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](../index.html). For
an end-to-end purchasing and verification example, see [Buy a DID Number That
Requires Verification](../../../examples/buy-dids-with-verification.html).

## Upload requirements

- Retrieve the current key through [Get Public Keys](public-keys.html) before encrypting
  the document.
- Follow [Encryption Details](encryption-details.html) 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](public-keys.html) and [Encryption Details](encryption-details.html).

```
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-encrypted-files.html).

```
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-encrypted-file.html).

```
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](create-encrypted-files.html).

```
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-encrypted-files.html).

```
DELETE /v3/encrypted_files/{id}
```

## Data reference

See [Encrypted Files Object](encrypted-files-object.html) for the returned metadata and
upload fields. See [Encryption Details](encryption-details.html) for the encryption and
fingerprint process.

## How an uploaded file is used

| Target resource | Use |
| --- | --- |
| [Proof](../proofs/index.html) | Link the Encrypted File with an accepted Proof Type and the relevant Identity or Address. |
| [Permanent Supporting Document](../permanent-documents/index.html) | Link one or more Encrypted Files with a permanent Supporting Document Template and an Identity. |
| [Address Verification](../address-verifications/index.html) | 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](public-keys.html) - Retrieve the RSA keys required before encrypting a
  document.
- [Encryption Details](encryption-details.html) - Implement file encryption and
  fingerprint calculation.
- [Proofs](../proofs/index.html) - Link an uploaded file as accepted evidence for an
  Identity or Address.
- [Supporting Document Templates](../supporting-document-templates/index.html) - Retrieve
  regulatory forms that must be completed and uploaded.
- [Permanent Supporting Documents](../permanent-documents/index.html) - Link reusable
  completed forms to an Identity.
- [Address Verifications](../address-verifications/index.html) - Submit one-time encrypted
  files with a verification task.

On this page