From 6a33bb370e5296bb82cc85070c84157b1004ad9b Mon Sep 17 00:00:00 2001 From: Burak Oztopuz Date: Sun, 2 Aug 2026 17:34:44 +0000 Subject: [PATCH 1/3] docs(CSM-357): document app-level API key scoping for App Store Connect Team API keys always span every app in the account. Add a dedicated section explaining that an app-scoped key requires an individual key generated by a service account user restricted to selected apps, and note the signing limitation that comes with a non-Admin role. --- .../adding-an-app-store-connect-api-key.md | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) 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 082a1def..1202c9c6 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,43 @@ 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 supports per-app access. Only these roles can be restricted to selected apps: **App Manager**, **Developer**, **Marketing**, **Sales** and **Customer Support**. +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, go to **Users and Access > Integrations > App Store Connect API**, open the **Individual Keys** section and generate a new key. The key inherits the user's role and app restrictions, so it can act on the selected apps only. + +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. + +::: + ### Downloading the Key After generating the key, download the key file by pressing Download API Key next to it. From 144101fb43fb3f1b0ee6031e66decff5dcd80b2d Mon Sep 17 00:00:00 2001 From: Burak Oztopuz Date: Sun, 2 Aug 2026 17:41:07 +0000 Subject: [PATCH 2/3] docs(CSM-357): address CodeRabbit review feedback - Generate the individual key from the user profile (Edit Profile > Individual API Key), not Users and Access > Integrations. - Note that Sales only supports Selected Apps while Access to Reports is disabled, and that Certificates, Identifiers & Profiles access also forces all-app scope. - Note that individual keys cannot reach Sales and Finance endpoints. - Hyphenate 'app-scoped'. --- .../adding-an-app-store-connect-api-key.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) 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 1202c9c6..612c85dd 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 @@ -90,19 +90,25 @@ To obtain a key that only works on designated apps, you need an **individual key #### 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 supports per-app access. Only these roles can be restricted to selected apps: **App Manager**, **Developer**, **Marketing**, **Sales** and **Customer Support**. +2. Assign a role that supports per-app access. Only these roles can be restricted to selected apps: **App Manager**, **Developer**, **Marketing**, **Customer Support** and **Sales**. **Sales** qualifies only while **Access to Reports** is left disabled, granting that permission gives the user access to all apps. The same applies to the **Certificates, Identifiers & Profiles** permission: a user who has it always has all-app access. 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, go to **Users and Access > Integrations > App Store Connect API**, open the **Individual Keys** section and generate a new key. The key inherits the user's role and app restrictions, so it can act on the selected apps only. +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. +**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. ::: @@ -110,6 +116,8 @@ Download the `.p8` file and add it to Appcircle exactly as described in [Linking 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 From 23a18898997a4af6771104bd3b562032ac0fb103 Mon Sep 17 00:00:00 2001 From: Burak Oztopuz Date: Sun, 2 Aug 2026 17:52:04 +0000 Subject: [PATCH 3/3] docs(CSM-357): drop Sales from the app-scoped service account roles Sales can be restricted to selected apps, but Apple does not allow the Sales role to generate an individual API key (eligible roles: Account Holder, Admin, App Manager, Customer Support, Developer, Marketing), so a Sales service account cannot produce an app-scoped key at all. --- .../security/credentials/adding-an-app-store-connect-api-key.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 612c85dd..9f0dbeb5 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 @@ -90,7 +90,7 @@ To obtain a key that only works on designated apps, you need an **individual key #### 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 supports per-app access. Only these roles can be restricted to selected apps: **App Manager**, **Developer**, **Marketing**, **Customer Support** and **Sales**. **Sales** qualifies only while **Access to Reports** is left disabled, granting that permission gives the user access to all apps. The same applies to the **Certificates, Identifiers & Profiles** permission: a user who has it always has all-app access. +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.