# Link Apple Developer Account to Onside

Connecting your Apple Developer account is a crucial step that allows Onside to securely and automatically sync your app builds. This guide will walk you through the two parts of the connection process: generating an **API Key** and a **Marketplace Token**.

{% hint style="warning" %}
To complete this process, you will need **Admin** access to your App Store Connect account.
{% endhint %}

***

### Part 1: Generating and Submitting Your API Key

The API Key allows Onside to communicate with App Store Connect on your behalf to manage app information.

<div align="left"><figure><img src="https://3698875069-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FV24VBLkTP47H3Kf48DFs%2Fuploads%2FfcI8L4wFHAFC3mHeuIWi%2Fimage.png?alt=media&#x26;token=7ceb288f-2c9b-45d2-9d38-5ac7de04f231" alt="" width="563"><figcaption></figcaption></figure></div>

{% stepper %}
{% step %}

#### Go to the API Keys Section in App Store Connect

Click this direct link to open the correct page:

<a href="https://appstoreconnect.apple.com/access/integrations/api" class="button secondary" data-icon="link">Go to App Store Connect Keys →</a>

You will land on the **Users and Access > Integrations > App Store Connect API** page.
{% endstep %}

{% step %}

#### Generate a New API Key

Click the **(+)** button to generate a new key. In the pop-up window:

1. **Name:** Give the key a memorable name, like "Onside Marketplace".
2. **Access:** Assign it the **App Manager** or **Admin** role.
3. Click **Generate**.
   {% endstep %}

{% step %}

#### Download the .p8 Key File

After generating the key, you will see a new entry in your list of active keys. Click the **Download** button.

{% hint style="danger" %}
You can only download the `.p8` key file **once**. Please save it in a secure location, as you will need to upload it to Onside.
{% endhint %}
{% endstep %}

{% step %}

#### Copy & Paste Credentials into Onside

On the same App Store Connect page, you will find your **Issuer ID** and the **Key ID** for the new key you just created.

1. **Copy** the **Issuer ID**.
2. **Copy** the **Key ID**.
3. Go back to the Onside Console "Link Developer account" page.
4. **Paste** the **Apple Developer ID (Issuer ID)** into the corresponding field.
5. **Upload** the `.p8` file you downloaded.
6. **Paste** the **Key ID** into its field.
7. Click **Submit**.

<details>

<summary><strong>Is it safe to give you an API Key with Admin access? Can you delete my app?</strong></summary>

We understand this concern completely. Security and trust are fundamental to our partnership with developers.

* **Secure, Encrypted Storage:** Once you provide the API key, it is immediately encrypted and stored securely in our system. It is never exposed in plain text.
* **Purpose-Built Operations:** Our systems are designed to use the API key for specific, necessary operations only, such as syncing app builds, viewing metadata, and managing app availability on Onside. We do not have automated or manual processes designed to delete your apps from App Store Connect.
* **Your Control:** You always remain in full control. You can revoke the API key you generated for Onside at any time in your App Store Connect account, which will immediately cut off our access.

We require the Admin or App Manager role because these are the roles Apple has designated with the necessary permissions to manage builds and app metadata through the API. We are committed to using this access responsibly and only for the stated purposes of operating the Onside marketplace.

</details>

<details>

<summary><strong>Do I need a separate API Key for each of my apps?</strong></summary>

No. You only need to generate **one** App Store Connect API Key for Onside. This single key will allow us to sync all the apps you choose to make available on our platform from your developer account.

</details>

<details>

<summary><strong>What happens if my `.p8` API Key file is lost or compromised?</strong></summary>

If you lose the `.p8` file before uploading it to us, or if you suspect it has been compromised, you should immediately go to App Store Connect and **revoke that specific API key**. The key will instantly become invalid. You can then generate a new one and update the credentials in your Onside Console. The old, revoked key will no longer provide any access.

</details>

<details>

<summary><strong>Can I use an existing API Key that I use for other services?</strong></summary>

Yes, you can, provided it has the required **Admin** or **App Manager** permissions. However, for security and better management, we **highly recommend generating a new, dedicated API Key specifically for Onside** and naming it accordingly (e.g., "Onside Marketplace"). This makes it easy to track and manage access, and if you ever need to revoke access for one service, it won't affect others.

</details>
{% endstep %}
{% endstepper %}

### Part 2: Generating and Submitting Your Marketplace Token

The Marketplace Token specifically authorizes Onside to distribute your selected apps.

<div align="left"><figure><img src="https://3698875069-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FV24VBLkTP47H3Kf48DFs%2Fuploads%2FpujzpfATGLjdkUpg27oX%2Fimage.png?alt=media&#x26;token=dc8e09a3-848e-4482-87ca-6d9163f7035e" alt="" width="563"><figcaption></figcaption></figure></div>

{% stepper %}
{% step %}

#### Sign the Alternative Terms Addendum

Before you can generate a token, you must accept Apple's "Alternative Terms Addendum for Apps in the EU". You will be prompted to do this in App Store Connect if you haven't already.

<a href="https://developer.apple.com/contact/request/alternative-eu-terms-addendum/" class="button secondary" data-icon="file-signature">Sign the Alternative Terms Addendum →</a>
{% endstep %}

{% step %}

#### Go to the Marketplace Distribution Section

In App Store Connect, navigate to **Users and Access > Alternative Distribution**.
{% endstep %}

{% step %}
**Connect your marketplace token**

* Click the **Add Marketplace** button.
* **Copy the Marketplace Token from the Onside Console** and paste it into the field in App Store Connect.&#x20;
  {% endstep %}

{% step %}

#### Select Apps and Enable Notifications

* **Select the apps** you want to make available for distribution on Onside. Click **Next**.
* When asked about App Notifications, select **"Yes, send notifications to this marketplace."** This is required for Onside to receive important updates about your apps.
* Click **Save**.
  {% endstep %}

{% step %}

#### Submit to Onside

Once the Marketplace is configured in App Store Connect, return to the Onside Console page and click **"It's done"** to finalize the process.
{% endstep %}
{% endstepper %}

***

### Troubleshooting & FAQs

<details>

<summary><strong>Why is this connection necessary?</strong></summary>

Onside does not accept direct app build uploads. Instead, we securely sync your builds directly from your App Store Connect account. This streamlined process means you only need to upload your builds to one place, and we handle the rest. This connection also enables us to auto-sync metadata like descriptions and screenshots, saving you time.

</details>

<details>

<summary><strong>Why do I need both an API Key and a Marketplace Token?</strong></summary>

These two credentials serve different purposes as required by Apple's system:

* The **API Key** grants us general, secure access to your App Store Connect account to perform technical actions like syncing builds and metadata.
* The **Marketplace Token** is a specific, explicit permission you grant within App Store Connect that authorizes Onside to act as an alternative marketplace for distributing your apps in the EU.

Both are necessary to create a secure and fully authorized connection between your developer account and the Onside platform.

</details>

<details>

<summary><strong>I'm seeing an error toast. What does it mean?</strong></summary>

Here are some common errors and how to solve them:

* **"This Apple Developer ID is already linked..." or "...already in use"**: This means the Apple Developer account has already been connected to another Onside account. An Apple Developer account can only be linked to one Onside account at a time.
* **"The API Key or Key ID you provided is incorrect"**: Double-check that you have copied and pasted the **Issuer ID** and **Key ID** correctly, without any extra spaces.
* **"Make sure the API Key has at least the App Manager role"**: When you generated the key in App Store Connect (Step 2 of Part 1), you may have selected a role with insufficient permissions. Please generate a new key with either the **App Manager** or **Admin** role.

</details>

<details>

<summary><strong>I don't see the "Integrations" tab or "Team Keys" section in App Store Connect.</strong></summary>

This typically means you do not have the required **Admin** role for your App Store Connect account. Only users with the Admin role can view this section and generate API keys. Please contact the Account Holder or an existing Admin on your team to either grant you Admin access or to generate the API key for you.

</details>

<details>

<summary><strong>I don't see the "Alternative Distribution" or "Marketplace" tab.</strong></summary>

This section is only visible to accounts that are eligible for alternative marketplace distribution under Apple's terms for the EU. Please ensure:

1. You have accepted the "[Alternative Terms Addendum for Apps in the EU.](https://developer.apple.com/contact/request/alternative-eu-terms-addendum/)" If you believe you are eligible but cannot see this section, you may need to contact Apple Developer Support.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onside.io/console/getting-started-and-publishing/link-apple-developer-account-to-onside.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.