diff --git a/docs/account/my-organization/security/credentials/adding-an-app-store-connect-api-key.md b/docs/account/my-organization/security/credentials/adding-an-app-store-connect-api-key.md index 082a1de..9f0dbeb 100644 --- a/docs/account/my-organization/security/credentials/adding-an-app-store-connect-api-key.md +++ b/docs/account/my-organization/security/credentials/adding-an-app-store-connect-api-key.md @@ -75,12 +75,51 @@ The role you assign to the key determines which Appcircle features it can suppor If signing is managed outside Appcircle (you create certificates, provisioning profiles and Bundle IDs yourself and add them manually under **Signing Identities**), an **App Manager** key is sufficient for the upload-focused flow: it can upload binaries to TestFlight, manage builds and testers, update metadata and submit to the App Store. An App Manager key **cannot** access Certificates, Identifiers & Profiles, so Appcircle's automatic signing will fail with that key. A **Developer** key can upload builds and manage internal testers and build information, but cannot edit App Store metadata or submit to the App Store. -You can also grant access to certain users on a per-app basis, but this requires additional configuration in App Store Connect under **Users and Access**. +If you need a key that can act on certain apps only instead of every app in your team, see [Restricting the API Key to Specific Apps](#restricting-the-api-key-to-specific-apps) below. To see a list of permissions each role has, visit: [https://developer.apple.com/support/roles/](https://developer.apple.com/support/roles/) ::: +### Restricting the API Key to Specific Apps + +A key generated under **Users and Access > Integrations > App Store Connect API** is a **team key**. Its role defines *what* the key can do, but its access always covers **all apps** in the team. There is no per-app restriction for a team key. + +To obtain a key that only works on designated apps, you need an **individual key**, which is generated by a specific App Store Connect user and inherits that user's role **and** their app-level restrictions. The recommended approach is to create a dedicated service account user in App Store Connect, limit that user to the apps Appcircle should manage, and generate the API key from that user. + +#### Creating a Service Account User Limited to Specific Apps + +1. In App Store Connect, go to **Users and Access > Users** and click the **+** button to invite a new user. Use a mailbox your team controls (for example, `appcircle-ci@yourcompany.com`) so that the account is not tied to a single employee. +2. Assign a role that both supports per-app access and can generate an individual key: **App Manager**, **Developer**, **Marketing** or **Customer Support**. Do not grant the user **Access to Reports** or **Certificates, Identifiers & Profiles**, either permission gives the account access to all apps and removes the app restriction. +3. In the same form, choose **Selected Apps** instead of **All Apps** and select only the apps that Appcircle should be able to access. +4. Complete the invitation and sign in as that user to accept it. + +#### Generating the API Key as That User + +While signed in as the service account user, click the **username** in the top right corner, select **Edit Profile**, and under **Individual API Key** press **Generate Key**. The key inherits the user's role and app restrictions, so it can act on the selected apps only. + +:::caution + +Individual keys are generated from the user's own profile, not from **Users and Access > Integrations > App Store Connect API**, which manages team keys. Each user can have only one active individual key at a time. If the **Generate Key** button is missing, an Account Holder or Admin must grant the user the **Generate Individual API Keys** permission. + +::: + +Download the `.p8` file and add it to Appcircle exactly as described in [Linking Appcircle with App Store Connect](#linking-appcircle-with-app-store-connect). + +:::caution + +**Account Holder**, **Admin** and **Finance** roles always have access to all apps and cannot be restricted per app. A key created by a user with one of these roles is not app-scoped, even if it is an individual key. + +::: + +:::info + +Because an app-scoped key requires a role other than Admin, it cannot access **Certificates, Identifiers & Profiles**. Appcircle's automatic signing (creating and downloading certificates and provisioning profiles) will not work with such a key. Use it for the upload-focused flow (TestFlight uploads, build and tester management, metadata and App Store submission, as allowed by the selected role) and either manage signing files manually under **Signing Identities** or add a separate Admin key for signing. + +Individual keys also cannot reach the Sales and Finance report endpoints of the App Store Connect API. Those endpoints require a team key with the matching role. + +::: + ### Downloading the Key After generating the key, download the key file by pressing Download API Key next to it.