Add CLI token support for app management and BP API

[zzooeeyy]

WHY are these changes introduced?

Closes

• https://github.com/shop/issues-app-access/issues/689

WHAT is this pull request doing?

Add support to use the CLI token for app management API

• Remove isAppManagementDisabled() function that disables App Management API if a CLI Token is provided
• Perform token exchange with AppMangement API and BusinessPlatform API if a CLI token is provided when creating a session for AppManagmentClient, and assign those access token as a ServiceAccount user
• Extend UserInfo query to get the first 2 organizations the user/CLI token service account belongs to
  • This assumes the CLI Token will always only belong to a single organization and raise an exception if the CLI Token belong in multiple orgs
• ⚠️ With this change, CLI Tokens will be used to exchange for Partners API, BP API and App Management API, the token exchange requests will fail if the CLI token does not contain enough scopes.
  • ‼️This will break existing CLI Tokens unless this scope backfill is complete ‼️
  • https://github.com/shop/issues-app-access/issues/703
  • 

How to test your changes?

• ➡️ Demo Video

Steps

1. Ensure Partners org permission is synced to Dev Dash (steps)
2. Enable beta "Add app management scope to CLI token" for your org in Partners internal
3. Create a new CLI Token for your org
4. Use the CLI token for apps within your partner and dev dash org with the CLI snapshot version 20250414215916
npm i -g @shopify/[email protected] --@shopify:registry=https://registry.npmjs.org

Tested flows

• ✅ With CLI Token, shopify app config link a Partners app

• ✅ With CLI Token, shopify app config link a dev dash app

• ✅ With CLI Token, shopify app deploy a dev dash app

• ✅ With CLI Token, shopify app deploy a Partners app

• ✅ With a user session, shopify app config link a Partners app

• ✅ With a user session, shopify app config link a dev dash app

• ✅ With a user session, shopify app deploy a dev dash app

• ✅ With a user session, shopify app deploy a Partners app

• ✅ With CLI token, shopify app info to display a Partners app
  

• ✅ With CLI token, shopify app info to display a dev dash app
  

Post-release steps

‼️This will break existing CLI Tokens unless this scope backfill is complete ‼️

• https://github.com/shop/issues-app-access/issues/703

Measuring impact

How do we know this change was effective? Please choose one:

• n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
• Existing analytics will cater for this addition
• PR includes analytics changes to measure impact

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

[zzooeeyy]

• Add CLI token support for app management and BP API #5604 : 2 dependent PRs (#5622 , #5627 ) 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	76.68% (+0.04% 🔼)	9492/12378
🟡	Branches	71.77% (-0.09% 🔻)	4657/6489
🟡	Functions	76.45% (+0.06% 🔼)	2461/3219
🟡	Lines	77.22% (+0.05% 🔼)	8977/11625

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🔴	... / app-management-client.ts	41.58% (-0.88% 🔻)	35.71% (-2.75% 🔻)	40% (-0.4% 🔻)	40.15% (-0.76% 🔻)
🟡	... / local.ts	68.52% (-0.57% 🔻)	56.6%	52.17% (-1.99% 🔻)	68.52% (-0.57% 🔻)

Test suite run success

2213 tests passing in 961 suites.

Report generated by 🧪jest coverage report action from 68b53f6

[zzooeeyy]

/snapit

[isaacroldan]

This will break old CLI tokens only if they try to access the app-management API right?

[isaacroldan]

🎩 'ed and works, left two small comments but pre-approving, feel free to merge once those are addressed :)

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/node/context/local.d.ts

@@ -25,13 +25,6 @@ export declare function isDevelopment(env?: NodeJS.ProcessEnv): boolean;
  * @returns True if SHOPIFY_FLAG_VERBOSE is truthy or the flag --verbose has been passed.
  */
 export declare function isVerbose(env?: NodeJS.ProcessEnv): boolean;
-/**
- * It returns true if the App Management API is disabled.
- * This should only be relevant when using a Partners token.
- *
- * @returns True if the App Management API is disabled.
- */
-export declare function isAppManagementDisabled(): boolean;
 /**
  * Returns true if the environment in which the CLI is running is either
  * a local environment (where dev is present) or a cloud environment (spin).

packages/cli-kit/dist/private/node/session/exchange.d.ts

@@ -26,15 +26,33 @@ export declare function exchangeAccessForApplicationTokens(identityToken: Identi
  */
 export declare function refreshAccessToken(currentToken: IdentityToken): Promise<IdentityToken>;
 /**
- * Given a custom CLI token passed as ENV variable, request a valid partners API token
+ * Given a custom CLI token passed as ENV variable, request a valid Partners API token
  * This token does not accept extra scopes, just the cli one.
- * @param token - The CLI token passed as ENV variable
+ * @param token - The CLI token passed as ENV variable 
  * @returns An instance with the application access tokens.
  */
 export declare function exchangeCustomPartnerToken(token: string): Promise<{
     accessToken: string;
     userId: string;
 }>;
+/**
+ * Given a custom CLI token passed as ENV variable, request a valid App Management API token
+ * @param token - The CLI token passed as ENV variable 
+ * @returns An instance with the application access tokens.
+ */
+export declare function exchangeCliTokenForAppManagementAccessToken(token: string): Promise<{
+    accessToken: string;
+    userId: string;
+}>;
+/**
+ * Given a custom CLI token passed as ENV variable, request a valid Business Platform API token
+ * @param token - The CLI token passed as ENV variable 
+ * @returns An instance with the application access tokens.
+ */
+export declare function exchangeCliTokenForBusinessPlatformAccessToken(token: string): Promise<{
+    accessToken: string;
+    userId: string;
+}>;
 type IdentityDeviceError = 'authorization_pending' | 'access_denied' | 'expired_token' | 'slow_down' | 'unknown_failure';
 /**
  * Given a deviceCode obtained after starting a device identity flow, request an identity token.

packages/cli-kit/dist/private/node/session/scopes.d.ts

@@ -13,4 +13,10 @@ export declare function allDefaultScopes(extraScopes?: string[]): string[];
  * @param extraScopes - custom user-defined scopes
  * @returns Array of scopes
  */
-export declare function apiScopes(api: API, extraScopes?: string[]): string[];
\ No newline at end of file
+export declare function apiScopes(api: API, extraScopes?: string[]): string[];
+/**
+ * Returns specific scopes required for token exchange with the given API.
+ * @param api - API to get the scopes for
+ * @returns Array of transformed scopes
+ */
+export declare function tokenExchangeScopes(api: API): string[];
\ No newline at end of file