[DEVECO-1007] Rework Build Apps & Integrations; document Public Scoped Apps (EA) - #144
Draft
gaberduty wants to merge 6 commits into
Draft
[DEVECO-1007] Rework Build Apps & Integrations; document Public Scoped Apps (EA)#144gaberduty wants to merge 6 commits into
gaberduty wants to merge 6 commits into
Conversation
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 <noreply@anthropic.com>
Collapse 12 sidebar entries to 8, organized around what the reader is
doing rather than around individual platform features. Several pages
were thin enough that they only added a navigation step: API Picker was
a single table, App Functionality was a table of links plus the add and
remove UI steps, and Writing App Event Transformers documented the
transformer API on a separate page from the one telling you to write a
transformer. Registering an app and making it useful took four pages.
Structure:
- App Overview absorbs App Functionality and API Picker, so the
"what can I build" tables sit on the page that asks the question.
- Private Apps (new) becomes the home for Scoped OAuth, which was
previously spread across three pages despite being one story: an
app that only works on the account that created it. It covers the
per-resource scopes, the client credentials app token flow, the
confidential-client and mandatory-PKCE requirements, and the fact
that these apps are never reviewed or published. It also documents
writing one Event Transformer on an app and reusing it across every
service that receives the payload, which is a common reason to
register a private app in the first place.
- Developer Account gains a lead section describing the account and
its limits, with the existing Q&As kept verbatim under an FAQ
heading.
- Register an App absorbs the add/remove functionality steps from App
Functionality and Events Integration, so registering and configuring
an app is one page.
- Events Integration Functionality absorbs Writing App Event
Transformers.
- OAuth Functionality absorbs User OAuth Token and hands the Scoped
material to Private Apps, keeping the shared user-token flow that
#143 unified rather than re-splitting it per functionality.
Slugs are preserved for every page that survives, including
developer-account-faq, whose title changes to "Developer Account" but
whose slug does not. Five slugs die with their pages and need Stoplight
redirects: app-functionality, api-picker, writing-app-event-transformers,
user-oauth-token, app-oauth-token.
Also:
- Repoint the five inbound links from other doc sections. The REST API
rate limit page linked both its app-token and user-token mentions at
OAuth Functionality; they now point at the two separate flows.
- Replace a hardcoded developer.pagerduty.com URL in the FAQ with a
relative link.
- Normalize heading levels on Register an App and Events Integration,
where intro sections sat at h3 above h2 siblings.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
gaberduty
changed the title
Replaces the TODO placeholder with the installation page as an account
admin sees it.
The screenshot also settles two things the surrounding prose was vague
about, so it has been tightened to match:
- The Details panel lists "Token types: User tokens", so an admin can
see the user-token limitation before installing.
- The page tells the admin that users still complete the OAuth flow
individually. Installing does not by itself grant the app any
access, it only permits users on that account to authorize it —
worth stating plainly, since a button labelled "Install on your
account" reads like it grants access at that moment.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
TODO: revert before merge. The page is meant to stay out of toc.json so it is reachable but unadvertised, but an unlisted page has no derivable URL to visit on staging — Stoplight assigns the node id at sync time — so there is no way to review it without a sidebar entry. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
There are only two kinds of app functionality, Events Integration and
OAuth, but the page listed four things side by side: Events Integration,
Simple Install Flow, Classic User OAuth, and Scoped OAuth. That presents
Simple Install Flow as a peer of the functionality it is part of, and
splits OAuth into two entries before the reader knows what OAuth is for.
Now two subsections:
- Events Integration covers machine events over the async Events API,
high volume and Event Intelligence, with change events as the
informational variant. Simple Install Flow and Event Transformers
are described as optional pieces of it rather than as peers.
- OAuth covers the REST API for managing PagerDuty resources, and the
human-initiated incident case with its synchronous, 1-per-second
caveat and a pointer back to Events Integration for volume. Classic
and Scoped are kinds of OAuth rather than top-level functionality.
Add-ons, webhooks, and REST API tokens are not app functionality at all
and are configured outside app registration, so they now sit under
"Other ways to integrate with PagerDuty" which says so.
This absorbs the API Picker table. Its rows restated the same material
as "what do you want to do" and every one of them lands in one of the
sections above.
Also answer "Can my app be used by other PagerDuty accounts?" directly,
in terms of private versus public use.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review feedback on the App Overview page: * Drop "without you hosting anything" from the Event Transformer bullet * Correct the /incidents rate limit: it is an operation-specific limit of 300 req/min, not 1 incident per second * Clarify the two kinds of OAuth functionality: Classic User OAuth acts as a user via an authorization code grant; Scoped OAuth scopes access per resource type and supports both the authorization code and client credentials grants * Point the webhooks block at /webhook_subscriptions instead of the deprecated /extensions endpoint The old api-reference.pagerduty.com/#!/ URLs no longer resolve, so replace all 10 of them repo-wide with their developer.pagerduty.com equivalents. Two were pointing at the wrong endpoint and are corrected in the process: the Events API v2 overview linked to list-incidents where it meant create-an-incident, and the Incident Creation API page linked to create-an-incident where it meant update-an-incident. Also update the moved add-ons support links to support.pagerduty.com/main. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DEVECO-1007
Two related changes to the Build Apps & Integrations section. Reviewing commit-by-commit is probably easiest.
1. Public Scoped Apps (Early Access)
A new page for developers trying out Public Scoped Apps, which extend Scoped OAuth so a single app can be used across many accounts.
https://app.pagerduty.com/oauth_apps/[app_id], with a screenshot of the installation page the admin sees.client_secretmust still be secured and PKCE is still required.Not linked in
toc.json, so it renders at its slug but isn't advertised — same treatment as20-Early-Access-Webhooks.md.Per review, the non-EA pages describe the platform exactly as it is today and never mention Early Access. The EA page carries the whole delta, and ends with a table naming each non-EA statement that does not hold for participants.
2. Section restructure
12 sidebar entries collapse to 8, organized by what the reader is doing:
Private Apps is the substantive new page. Scoped OAuth was spread across three pages despite being one story — an app that only works on the account that created it. It now covers per-resource scopes, the client-credentials app token flow, the confidential-client and mandatory-PKCE rules, that these apps are never reviewed or published, and the Event Transformer reuse pattern (write the transform once on the app, add that integration to every service receiving the payload).
The Scoped/Classic split follows the review note: Private Apps owns the Scoped story and links to OAuth Functionality for the concrete flow, so the auth-code flow that #143 unified is not re-split per functionality.
Redirects live in
developer-site/dev-doc-redirect.js, not in this repo. Handled separately, after this merges — the new pages' Stoplight node ids do not exist until the docs sync. Recording the analysis here so the follow-up is mechanical.Published URLs are
/docs/<stoplight-node-id>-<slugified-H1>. The slug comes from the page H1, not thetoc.jsonslug, and the node id is assigned by Stoplight. Verified against72d3b724589e3-rest-api-rate-limits(H1 "REST API Rate Limits", toc title "Rate Limits") ande518101fde5f3-obtaining-an-app-o-auth-token(H1 "Obtaining an App OAuth Token", toc title "App OAuth Token").Consequences:
Entries whose targets this PR invalidates:
/docs/api-picker→.../api-picker/ZG9jOjExMDI5NTcx-api-pickers/docs/app-functionality→.../app-functionality/ZG9jOjExMDI5NTcw-app-functionality-overview/docs/oauth-2-functionality-app-tokene518101fde5f3-obtaining-an-app-o-auth-token/docs/developer-account→.../developer-account/ZG9jOjExMDI5NTY4-developer-account-faqAlready broken on
mainbefore this PR — #143 deleted the PKCE and Code Grant pages without updating these. All four should point at OAuth Functionality (f59fdbd94ceab-o-auth-functionality), which still exists:/docs/oauth-2-functionality-pkce/docs/oauth-2-functionality-client-secret/docs/app-integration-development/oauth-2-pkce//docs/app-integration-development/oauth-2-auth-code-grant/writing-app-event-transformersanduser-oauth-tokenhave no legacy entries in the map, so nothing to retarget.Verification
.mdlinks and anchors acrossdocs/, plus all 30 image refs: no breakage introduced. Six broken links inREST-API/andevents-API-v1/and four orphaned images inassets/— all confirmed pre-existing onmain, left alone as out of scope.toc.jsonuri resolves.#add-an-event-transformeranchor is preserved — two other doc sections link to it.Open questions
app.pagerduty.com. If EU accounts needeu.pagerduty.com/oauth_apps/[app_id], that needs a line.🤖 Generated with Claude Code