# Add private images to wallet passes

Protect user privacy by storing images directly with Airship.

You can add publicly accessible images to a pass by upload when designing your template in the dashboard or by providing a URL when creating or updating a pass through the API. For images that should not be exposed publicly, such as a member's profile photo, a business card, or other personal content, add them as private images. Private images can only be viewed as part of the pass they're used in, not from a public URL.

## How private images work

Private images use an API-only workflow:

1. **Upload** — [Upload the raw image binary](#upload-a-private-image), and Airship returns its storage path.
1. **Reference** — [Use that path as an image field's value](#use-a-private-image-in-a-pass) when you create or update a pass.

The images must be in PNG format, and when uploading, you must specify a type, which determines how the image is resized. Each platform allows different types for specific uses. See the [`imageType` parameter](https://www.airship.com/docs/developer/rest-api/wallet/operations/images/#uploadimageprivate) for the resized dimensions.

### Google Wallet

Private images can only be used for a Google Wallet pass's main image, set on the `imageModulesData` field. The field requires a private image, and using the private path on any other Google image field causes the image to be dropped. Use the type `mainImage` in your upload call. It's resized to 180×180 pixels.

Airship uses Google's [Secure Private Images](https://developers.google.com/wallet/generic/use-cases/secure-private-images) feature to render the image. 

### Apple Wallet

Private images are not required for Apple Wallet passes, but they're recommended when an image is personal to the pass holder and shouldn't be accessible from a public URL. If the image doesn't need to be private, you can reference it with a public URL instead. Airship bundles a private image directly into the pass file.

You can use an Apple private image in any image field, but it's resized upon upload for the type you set:

- `thumbnail_image` is 180×180 pixels
- `strip_image` is 624×246 pixels

Make sure the field you use it in matches the type you picked when uploading, or the image may not render at the correct size.

### Multi-use

Reuse an uploaded image across multiple passes in the same project instead of uploading it again for each one.

Google's own private image reference only works for a single pass, but Airship generates a new one for each pass automatically, so you only need to upload the image once.

### Image data retention 

Airship automatically deletes a private image 13 months after upload, or 6 months after last access, whichever comes first. The following timestamps are used to calculate this period:

- Upload date — The day you call the upload endpoint
- Last access date — The day a pass is created via the API or a user opens an Adaptive Link that generates one

## Upload a private image

To upload an image, send a `POST` request to `https://wallet-api.urbanairship.com/v1/images/projects/{projectId}/{imageNameIdentifier}` with the raw binary PNG data as the request body. For supported authorization types and the full request and response definitions, see the [Upload image](https://www.airship.com/docs/developer/rest-api/wallet/operations/images/#uploadimageprivate) endpoint in the Wallet API reference.

**Upload a private image**

```http
POST /v1/images/projects/12345/test_image.png?imageType=mainImage HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: image/png
Api-Revision: 1.2

...
```


A successful upload returns `200 OK` with metadata about the stored image and the `path` you'll use to reference the image in a pass.

**Successful response**

```json
{
    "path": "passtools_prod/1/images/587ac4e3d188b0fcd4f05038d8814fefd82ac834_test_image.png",
    "source": "uploaded",
    "imageType": "mainImage",
    "width": 180,
    "height": 180
}
```


## Use a private image in a pass

Use the `path` from the upload response as the `value` for an image field when you create or update a pass. For Google Wallet, set it on the image module field `imageModulesData`. For Apple Wallet, set it on the `thumbnail_image` or `strip_image` field.

The following example shows the `imageModulesData` field referencing a private image on a Google Wallet pass. Include your pass's other fields as usual.

**Reference a private image in a pass**

```json
{
  "fields": {
    "imageModulesData": {
      "fieldType": "imageModulesData",
      "label": "Full-Width Image",
      "value": "passtools_prod/1/images/587ac4e3d188b0fcd4f05038d8814fefd82ac834_test_image.png"
    }
  }
}
```