> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage

> Keep proofing records, face reference photos and capture media in TruU managed storage or in your own Amazon S3 bucket or Azure Blob container. Exact permissions, setup, testing, encryption and migration.

This page is for the administrator and cloud engineer deciding where verification files live. When you finish you will know what is stored, how to connect your own bucket or container with least-privilege access, and how to test and migrate.

## What is stored

TruU IDV writes a small set of files outside its database, depending on your Proofing and Face settings.

| File | Written when | Controlled by |
| - | - | - |
| **Decision record** | A proofing check completes. One JSON file: outcome, scores, identity fields, warnings. | **Decision record** on [Proofing](https://docs.truu.ai/idv/factors/proofing/overview.md#what-is-stored) |
| **Proofing photo** | A proofing check passes; the verified selfie becomes the person's Face reference | **Proofing photo** on Proofing |
| **Capture media** | Proofing completes; ID images and liveness video | **Store capture videos** and **Store capture images** on Proofing (Didit) |
| **Face reference photos you already hold** | Never written; TruU only reads them | A photo source on [Face](https://docs.truu.ai/idv/factors/face.md) |

Audit records and verification requests aren't stored here. They stay in TruU's database and are exported from [Activity](https://docs.truu.ai/idv/admin/activity.md). See [Data handling](https://docs.truu.ai/idv/security/data-handling.md).

## TruU managed or your own

Open **Settings → Storage**.

![Storage settings showing the TruU managed store marked Write and Live, and an empty Your stores section with Add store](https://mintcdn.com/truu-2/ggexkQvmOZdl3yHs/images/idv/settings-storage-light.png?fit=max\&auto=format\&n=ggexkQvmOZdl3yHs\&q=85\&s=12351dcdd6db6560e011e60c17c53516)

* **TruU managed** is the default. Files go to storage TruU operates, separated per organization and encrypted at rest. Nothing to set up.
* **Your stores** are Amazon S3 buckets or Azure Blob containers you own, under your retention rules and, optionally, encrypted with a key only you hold.

Each store has **Read** access, **Write** access, or both:

* **Read:** Face uses this store to look up reference photos.
* **Write:** Proofing writes decision records and face-on-file deposits here.

You then choose a store where it's used: under **Store** on Proofing, and as a photo source on Face. A store shows **Live** when at least one factor uses it and **Idle** when none does yet, and **Encrypted** when face encryption is on.

> [!NOTE]
>
> If your cloud team can't provision a bucket yet, start on TruU managed storage, go live, and migrate later. Nothing else about your configuration changes.

## Before you start

* An **Owner** or **Admin** seat in TruU IDV.
* Someone who can create a bucket or container and a scoped credential in your cloud account.
* The bucket doesn't need to be public, and shouldn't be. TruU connects outbound over HTTPS; nothing is opened on your side.
* For face encryption: an AES key (16, 24 or 32 bytes; 32 recommended) that you generate and keep.

## Amazon S3

### Permissions

Create an IAM user (or role with access keys) dedicated to TruU, and attach an IAM policy scoped to the bucket and, if you use one, a key prefix.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TruUObjects",
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject"],
      "Resource": "arn:aws:s3:::YOUR-BUCKET/YOUR-PREFIX*"
    },
    {
      "Sid": "TruUList",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR-BUCKET"
    }
  ]
}
```

| Access in TruU | Actions needed |
| - | - |
| Read only | `s3:GetObject`, `s3:ListBucket` |
| Write | `s3:PutObject`, `s3:GetObject`, `s3:ListBucket` |

`s3:ListBucket` matters even though TruU never lists: without it, S3 answers a check for a missing object with 403 instead of 404. If the bucket uses default SSE-KMS encryption, also allow `kms:GenerateDataKey` and `kms:Decrypt` on the key.

### Fields

| Field | Example |
| - | - |
| **Bucket name** | `contoso-idv-verification` |
| **Region** | `us-east-1` |
| **Access key ID** and **Secret access key** | From the IAM user above |

## Azure Blob

### Permissions

Create a container for TruU. Choose how TruU authenticates:

| Authentication | What to provide | Notes |
| - | - | - |
| **Connection string** | The storage account's connection string | Simplest; grants account-wide access |
| **Account key** | **Storage account** name and an account key | Account-wide access |
| **SAS token** | **Storage account** name and a container-scoped SAS token | Least privilege. Recommended. |

For a SAS token, scope it to the container and grant only:

| Access in TruU | SAS permissions |
| - | - |
| Read only | Read |
| Write | Read, Write |

Set an expiry that matches your rotation schedule, and rotate the token in TruU before it expires.

### Fields

| Field | Notes |
| - | - |
| **Authentication** | Connection string, Account key or SAS token |
| **Container** | The container name |
| **Storage account** | Required for account key and SAS token; 3 to 24 lowercase letters and digits |

Account key and SAS token connect to the Azure public cloud (`core.windows.net`). For Azure US Government or China (`core.usgovcloudapi.net`, `core.chinacloudapi.cn`), use **Connection string**.

## Add the store

**1. Open Add store**

**Settings → Storage → Add store.** Choose **Amazon S3** or **Azure Blob** and enter the fields above. The store is named after the bucket or container.

**2. Choose access**

Tick **Read**, **Write** or both. At least one is required.

**3. Test the connection**

Choose **Test connection**. With Write ticked, TruU writes a small `.janus-probe` object (overwritten on each test, not deleted afterwards). With Read only, TruU checks it can read the bucket and writes nothing. The test times out after 10 seconds. A failed test shows the reason and nothing is saved.

**4. Connect, then use it**

Choose **Connect**. Then select the store under **Store** on [Proofing](https://docs.truu.ai/idv/factors/proofing/overview.md#what-is-stored), or add it as a photo source on [Face](https://docs.truu.ai/idv/factors/face.md). The store turns **Live** once a factor uses it.

[Credential health](https://docs.truu.ai/idv/admin/credential-health.md) checks each store daily and on demand. Credentials are held in a managed secrets service and never returned; replacing one deletes the old value, and every change is audited.

## Face encryption

Turn on face encryption for one of your stores to encrypt face photos with an AES key you supply. The store shows **Encrypted**.

* **AES mode:** GCM (recommended), CBC or CTR. CBC and CTR don't detect tampering; choose them only if your own tooling requires it.
* **Encoding:** how you paste the key: **Hex** or **Base64**.
* **GCM options** (GCM only):
  * **Include 1-byte key version (0x01) before the nonce**: on by default. Prefixes each file with a version byte so you can tell which key encrypted it when you rotate keys, and keeps files compatible with TruFace.
  * **Bind AAD to the object key**: off by default. Authenticates the file's full object key (its path in the bucket, UTF-8) as additional authenticated data, so a file copied or renamed to a different path fails to decrypt instead of being accepted.
* Changing the mode or GCM options requires re-entering the key.
* Keep the key somewhere durable. TruU can't read those photos back without it, and you'll need it (and the mode) to decrypt them yourself.

If you point Face at photos that are already encrypted in your bucket, turn decryption on here so Face can read them.

To decrypt files with your own tooling, the layout is:

| Mode | Layout |
| - | - |
| GCM | `[key version, 1 byte, if enabled] ‖ nonce (12 bytes) ‖ ciphertext ‖ tag (16 bytes)` |
| CBC, CTR | `IV (16 bytes) ‖ ciphertext` (CBC uses PKCS#7 padding) |

With **Bind AAD to the object key** on, pass the object key as the AAD when decrypting.

## Migrate from TruU managed storage

Files already in TruU managed storage stay readable after you add your own store. To move existing face photos and decision records into your store, turn on **Migrate data from TruU managed store** on a store with Write access, while adding it or later from its details. It's offered until one store has taken over from TruU managed storage. Confirm by typing the bucket or container name. Verification isn't interrupted while it runs, the migration is audited, and it can't be undone from the console.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Test connection fails with Write ticked | The credential can't put objects, or the prefix doesn't match the IAM policy | Allow `s3:PutObject` (or SAS Write) on the bucket and prefix |
| Test passes but Face can't find photos | The credential lacks `s3:ListBucket`, or the path template doesn't match | Allow `s3:ListBucket`; check the photo path on Face |
| Store stays **Idle** | No factor uses it yet | Select it under **Store** on Proofing or as a Face photo source |
| Can't decrypt photos yourself | Wrong key or mode | Use the same key, mode and encoding you set in TruU |

## Related

* [Proofing](https://docs.truu.ai/idv/factors/proofing/overview.md)
* [Face](https://docs.truu.ai/idv/factors/face.md)
* [Data handling](https://docs.truu.ai/idv/security/data-handling.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.