Changing a live application

Two regimes

While an application is a sandbox record or a production draft, PATCH /v1/developer/applications/{applicationId} edits it directly. Once production is approved and serving, that stops: a live application is changed through a release — the next version of the whole configuration, prepared beside what is serving — and through a small set of live changes that apply at once because they only ever narrow or stay inside what was already approved.

What needs review

Review is for material changes only. A release that contains none is approved the moment you submit it, with nobody reading it, and is ready to switch.

Everything else — description, website, support email, removing a redirect URI, removing a scope, adding a non-restricted scope, which publisher profile the application names — is ready to switch at once.

A release, start to finish

1. 1

   Create a draft

   POST …/releases makes a new draft prefilled from what production serves now. There is at most one open release per application.

2. 2

   Edit it

   PATCH …/releases/{releaseId} with any of name, description, websiteUrl, supportEmail, privacyPolicyUrl, termsUrl, redirectUris, allowedClaimScopes, allowedDataCategories, publisherProfileId, restrictedScopeJustifications. Anything else in the body is refused. POST …/releases/{releaseId}/bring-over with { fields: [...] } copies chosen fields from the sandbox record instead of retyping them.

3. 3

   Submit

   POST …/releases/{releaseId}/submit with { reason } when the release is material — the reason is required then, and read by the reviewer. A non-material release goes straight to approved.

4. 4

   Wait, or withdraw

   An in_review release can be withdrawn with POST …/releases/{releaseId}/withdraw. Staff may answer approved, changes_requested or rejected.

5. 5

   Rebase if production moved

   If a live change landed while the release was open, its base is stale and switching is refused with RELEASE_BASE_CHANGED. POST …/releases/{releaseId}/rebase carries your edits onto what production serves now; a release that is material afterwards goes back to draft.

6. 6

   Switch

   POST …/releases/{releaseId}/switch makes production serve the approved release from now on. It requires approved, a current base, and a passing go-live checklist — otherwise RELEASE_NOT_APPROVED, RELEASE_BASE_CHANGED or RELEASE_CHECKLIST_FAILING.

7. 7

   Switch back, within 30 days

   POST …/releases/switch-back returns production to the immediately previous version without review, for 30 days after it was replaced. After that it is RELEASE_SWITCH_BACK_EXPIRED; with nothing to go back to it is RELEASE_NO_PREVIOUS_VERSION.

GET …/releases lists every version with a summary — including blockedBy, the list of codes above that currently stop a switch, and readyToSwitch. GET …/releases/{releaseId} is one release in full.

Live changes that apply at once

PUT …/live-changes/redirect-uris with { redirectUris, reason? } and PUT …/live-changes/scopes with { allowedClaimScopes, allowedDataCategories?, reason? } send the whole intended list. The service splits it:

• Removals, a new path on an already-approved origin, and an added non-restricted scope apply immediately. The application's owners are told, and the change is recorded as applied by the owner.
• A new redirect domain or an added restricted scope joins the release — a draft prefilled from what is live, or the release already in progress — and is submitted for review with your reason (required then, up to 2000 characters). Production keeps its current values until you switch.
• At least one approved redirect URI must stay. Removing them all while a new domain waits for review is refused.

Both need the admin level on the application and a change_production_application passkey confirmation. They are refused while UnifyID holds the application under a staff-imposed status, while it is suspended or terminating, or while anything above it stops it serving.

GET …/live-changes lists change requests opened before releases existed — still decided by staff, still withdrawable with POST …/live-changes/change-requests/{changeRequestId}/withdraw — plus the open release and whether the application is live. New change requests are never opened.