# Set up store credentials for catalog import

> Add your App Store Connect or Google Play key as a credential so that Unity can read your product listings when you import a catalog.

To import an existing catalog from the App Store or Google Play, Unity needs a store API key that can read your product listings. Unity stores the key as a secret in [Secret Manager](/services/secret-manager.md) and reads it when you import. You can't view the value of the secret afterward.

You can add the credential in two ways:

* In the Unity Cloud Dashboard, the **Import catalog** dialog builds the credential from the key that the store issued to you. Use this method whenever you can, because Unity assembles and escapes the stored value for you.
* Alternatively, you can store the credential in Secret Manager yourself. Take this route if you import from the **Import Catalog** window in the Unity Editor, or if you manage your secrets outside the Unity Cloud Dashboard.

Whichever method you use, get the key from the store first. The following sections describe what Unity needs for each store, and what permissions that key needs to read your listings. A credential stored in the wrong shape is the most common reason an import fails, so use the dialog if you have the choice.

> **Note:**
>
> The following concerns a product or service (each a “Third Party Product”) that's not developed, owned, or operated by Unity. This information may not be up-to-date or complete, and is provided to you for your information and convenience only. Your access and use of any Third Party Product is governed solely by the terms and conditions of such Third Party Product. Unity makes no express or implied representations or warranties regarding such Third Party Products, and will not be responsible or liable, directly or indirectly, for any actual or alleged damage or loss arising from your use thereof (including damage or loss arising from any content, advertising, products or other materials on or available from the provider of any Third Party Products).

## Prerequisites

Before you set up a store credential, meet the following requirements:

* You have a role in your Unity organization or project that allows you to add secrets. For more information, refer to [Grant roles](/services/secret-manager/tutorials/grant-roles.md).
* You have an App Store Connect or Google Play account for the application whose catalog you want to import, with enough access to create an API key.
* Your application exists in the store account that the credential belongs to. Unity matches your application by its bundle ID or package name, so the credential and the application must belong to the same account.

## Set up an App Store Connect credential

Unity uses an App Store Connect API key to read your in-app purchase listings and their pricing. Create the key in App Store Connect under **Users and Access** > **Integrations**. For more information, refer to [Creating API keys for App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api) (Apple).

Unity needs three values from the key:

| Value       | Description                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Private key | The contents of the `AuthKey` `.p8` file that you download when you create the key. App Store Connect lets you download this file only once. |
| Key ID      | The identifier that App Store Connect shows next to the key.                                                                                 |
| Issuer ID   | Optional. The identifier that App Store Connect shows on the API keys page. Team keys have an issuer ID, and individual keys don't.          |

> **Important:**
>
> An individual key needs the **App Manager** role or higher, such as **Admin** or **Account Holder**, to read pricing. A key with a lower role can't read pricing information, so the import fails even though the credential itself is valid.

### Add the App Store Connect key in the Unity Cloud Dashboard

To build the credential from your key, follow these steps:

1. Open **In-App Purchases** > **Catalog**, then select **Import catalog**.
2. Select the **iOS** platform, open the credential dropdown, and select **Add credential**.
3. In **Secret name**, enter a name for the secret. Use 3 to 100 characters, start with a letter or a digit, and use only letters, digits, underscores (`_`), and hyphens (`-`). A bundle ID or package name isn't a valid secret name, because it contains periods (`.`).
4. In **Private key**, paste the contents of the `.p8` file, including the `BEGIN PRIVATE KEY` and `END PRIVATE KEY` lines.
5. In **Key ID**, enter the key ID from App Store Connect.
6. In **Issuer ID (team keys only)**, enter the issuer ID for a team key, or leave the field blank for an individual key.
7. Select **Add**.

Unity combines the values into a single JSON secret and saves it to Secret Manager at project scope, with access granted to In-App Purchase. Unity then selects the new credential in the dropdown, so you can continue the import.

If a value can't be a key, the dialog reports the problem inline and disables **Add**. Paste only the key itself into **Private key**, not an assembled JSON document, because the dialog builds the JSON around it for you.

If a key ID or issuer ID doesn't have the format the store usually issues, the dialog shows an advisory warning but still lets you continue. Apple doesn't publish either format as a contract, so Unity warns rather than blocks.

### Store the App Store Connect key in Secret Manager yourself

The secret value is a single JSON object with the following fields:

| Field      | Description                                                                                                     | Required |
| ---------- | --------------------------------------------------------------------------------------------------------------- | -------- |
| `p8`       | The full contents of the `.p8` private key file, including the `BEGIN PRIVATE KEY` and `END PRIVATE KEY` lines. | Yes      |
| `keyId`    | The key ID from App Store Connect.                                                                              | Yes      |
| `issuerId` | The issuer ID from App Store Connect. Leave the value empty for an individual key.                              | Yes      |

Because `p8` is a JSON string value, escape each line break in the private key as `\n`. If you paste the contents of the `.p8` file directly, the literal line breaks make the secret invalid JSON and the import fails.

Use the following shape for the secret value:

```json
{
  "p8": "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49\nAwEHBHkwdwIBAQQg...\n-----END PRIVATE KEY-----",
  "keyId": "A1B2C3D4E5",
  "issuerId": "12a34b56-c78d-9012-e345-6f78901a2345"
}
```

To store the credential, refer to [Store secrets using the Unity Dashboard](/services/secret-manager/tutorials/store-secrets.md), and grant the secret access to In-App Purchase.

> **Important:**
>
> Grant every credential you create yourself access to In-App Purchase. Unity lists only the secrets that grant it, so a credential without that access doesn't appear in the credential dropdown even though the secret saves successfully. For more information, refer to [Service access](/services/secret-manager/concepts/service-access.md).

## Set up a Google Play credential

Unity uses a Google Cloud service account key to read your in-app product listings through the Google Play Android Developer API. Create a service account and a JSON key for it in Google Cloud, under **IAM and Admin**. For more information, refer to [Create and delete service account keys](https://docs.cloud.google.com/iam/docs/keys-create-delete) (Google).

Unity needs the contents of the JSON key file that you download from Google Cloud. The file must contain the `client_email` and `private_key` members that Unity uses to request a token.

Two further requirements apply, and the import fails if you miss either of them:

* The service account has the **View app information (read only)** and **Manage store presence** permissions for your application, which you grant under **Users and permissions** in the Google Play Console.
* The Google Cloud project that owns the service account has the Google Play Android Developer API enabled.

For more information about both requirements, refer to [Getting started with the Google Play Developer API](https://developers.google.com/android-publisher/getting_started#service-account) (Google).

### Add the Google Play key in the Unity Cloud Dashboard

To build the credential from your key file, follow these steps:

1. Open **In-App Purchases** > **Catalog**, then select **Import catalog**.
2. Select the **Android** platform, open the credential dropdown, and select **Add credential**.
3. In **Secret name**, enter a name for the secret. Use 3 to 100 characters, start with a letter or a digit, and use only letters, digits, underscores (`_`), and hyphens (`-`). A bundle ID or package name isn't a valid secret name, because it contains periods (`.`).
4. In **Service account key**, paste the whole contents of the JSON key file. The dialog confirms which service account it read from the file.
5. Select **Add**.

Unity wraps the key file in a single JSON secret and saves it to Secret Manager at project scope, with access granted to In-App Purchase. Unity then selects the new credential in the dropdown, so you can continue the import.

Unity passes through any member of the key file that it doesn't recognize, so a change to the Google key format doesn't stop a valid key from working.

### Store the Google Play key in Secret Manager yourself

The secret value is a single JSON object with the following field:

| Field                | Description                                                                              | Required |
| -------------------- | ---------------------------------------------------------------------------------------- | -------- |
| `serviceAccountJSON` | The full contents of the service account key file that you downloaded from Google Cloud. | Yes      |

Because `serviceAccountJSON` is a JSON string value, JSON-escape the whole key file so that the secret is still valid JSON. Escape every backslash (`\`) as `\\`, and every double quote (`"`) as `\"`. Escape the line breaks between the members of the key file as `\n`, or remove them.

The backslash rule is the one that's easy to miss. The `private_key` member in the key file already holds `\n` escape sequences rather than real line breaks, so escaping its backslashes turns each sequence into `\\n` in the secret value. If you escape only the quotes and the line breaks, the value either isn't valid JSON, or it parses to a key file whose private key holds real line breaks. Either way, the import fails.

Use the following shape for the secret value:

```json
{
  "serviceAccountJSON": "{\"type\": \"service_account\", \"project_id\": \"my-project\", \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBgkq...\\n-----END PRIVATE KEY-----\\n\", \"client_email\": \"unity-catalog-import@my-project.iam.gserviceaccount.com\"}"
}
```

Escaping a key file by hand is error-prone. To produce the value reliably, read the file as a single string with a tool that escapes it for you. For example, `jq` writes the complete secret value with the following command:

```bash
jq -Rs '{serviceAccountJSON: .}' < service-account.json
```

To store the credential, refer to [Store secrets using the Unity Dashboard](/services/secret-manager/tutorials/store-secrets.md), and grant the secret access to In-App Purchase.

## Import with your credential

After you add the credential, use it in either import method:

* In the Unity Cloud Dashboard, select it in the credential dropdown. For more information, refer to [Import a catalog](./dashboard-catalog/import-catalog.md).
* In the Unity Editor, enter the secret name and its scope in the **Import Catalog** window. For more information, refer to [Import an existing catalog](./payment-providers/configure-remote-catalog.md#import-an-existing-catalog).

The credential dropdown in the Unity Cloud Dashboard lists the secrets stored at your project, the secrets your project inherits from your organization, and the secrets stored at the environment you're importing into.

If the import fails, refer to [Troubleshooting catalog import](./troubleshoot-catalog-import.md).

## Additional resources

* [Import a catalog](./dashboard-catalog/import-catalog.md)
* [Troubleshooting catalog import](./troubleshoot-catalog-import.md)
* [Create your Remote Catalog](./payment-providers/configure-remote-catalog.md)
* [Store secrets using the Unity Dashboard](/services/secret-manager/tutorials/store-secrets.md)
* [Service access](/services/secret-manager/concepts/service-access.md)