From 9ec39ced169a30f0df46c4130785775a1f2e6e47 Mon Sep 17 00:00:00 2001 From: Gabriel Durazo Date: Wed, 5 Aug 2026 15:48:49 -0500 Subject: [PATCH] [DEVECO-1007] Document Public Scoped Apps (Early Access) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an Early Access page for developers trying out Public Scoped Apps, which extend Scoped OAuth so a single app can be used across many PagerDuty accounts. The page covers the two constraints that distinguish it from a normal Scoped app: - Cross-account access is limited to user tokens. The client credentials flow still only issues an app token for the account that created the app, so any app-token-dependent behavior stays single-account. - A user can only authorize the app after an admin on their account has installed it, via https://app.pagerduty.com/oauth_apps/[app_id]. Also notes that going public does not relax the confidential-client requirement — a Scoped app must still secure its client_secret and use PKCE — since "many accounts can use this" invites the wrong inference. Left out of toc.json so the page is reachable but not advertised, as with Early Access Webhooks. A screenshot of the admin installation page is still to come, marked with a TODO. Co-Authored-By: Claude Opus 5 --- .../EA-Public-Scoped-Apps.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/app-integration-development/EA-Public-Scoped-Apps.md diff --git a/docs/app-integration-development/EA-Public-Scoped-Apps.md b/docs/app-integration-development/EA-Public-Scoped-Apps.md new file mode 100644 index 0000000..95f01d2 --- /dev/null +++ b/docs/app-integration-development/EA-Public-Scoped-Apps.md @@ -0,0 +1,54 @@ +--- +tags: [app-integration-development] +--- + +# Public Scoped Apps + + + +> ### Early Access +> +> The features described on this page are in an Early Access state and are subject to change. Please reach out to +> us if you have any questions or need support. + +Normally, a PagerDuty App with [Scoped OAuth functionality](08-OAuth-Functionality.md#scoped-oauth) is limited to a +single account — the one that created it. Public Scoped Apps extend Scoped OAuth so that a single app can be used +across many PagerDuty accounts, as [Classic User OAuth](08-OAuth-Functionality.md#classic-user-oauth) apps can be +today. + +## User tokens only + +A Public Scoped App can only obtain **user tokens** for other accounts, by taking a user on that account through the +[user token flow](09-User-OAuth-Token.md) to get their authorization and consent. + +The [client credentials flow](12-App-OAuth-Token.md), which issues an **app token** with no user involved, is not +available across accounts. An app token can still only be issued for the account that created the app. + +So when your app acts on another account, its access is the intersection of the scopes granted to the app and the +permissions of the authorizing user, as described for user tokens under +[Scoped OAuth](08-OAuth-Functionality.md#scoped-oauth). Any part of your app that relies on app-token access will only +work on your own account. + +The requirements of the user token flow are unchanged: a Scoped OAuth app is always a +[confidential client](08-OAuth-Functionality.md#confidential-vs-non-confidential-clients-and-pkce), so it must send its +`client_secret` on the token request and must use PKCE. Being usable by many accounts does not make it safe to +distribute the `client_secret` — a Public Scoped App still needs a server-side component that keeps the secret secure. + +## Installation by an account admin + +Before any user on another account can authorize your app, an admin on that account must install it. Until the app is +installed, authorization requests from users on that account will not succeed. + +To have your app installed on an account, give an admin on that account the following installation link, replacing +`[app_id]` with the ID of your app: + +``` +https://app.pagerduty.com/oauth_apps/[app_id] +``` + +The admin will be shown the app and the scopes it is requesting, and can install it for their account: + + + +Once the admin has completed the installation, users on that account can authorize your app through the +[user token flow](09-User-OAuth-Token.md) as normal.