Third-party Apps for Organizations

[dlozlla]

Description

Documents Organizations support for third-party applications, shipping with the GA Extended Functionality release (ROAD-5837). Third-party applications can now participate in Organization-context flows, gated by an explicit per-organization opt-in (third_party_client_access) at the org level and a domain-level connection at the connection level. M2M with Organizations was already shipped — this PR also closes documentation gaps in that area.

The work covers four concepts:

1. User flows — third-party applications support authorization code flow in an Organization context, with a dual opt-in requirement (org + domain connection).
2. Machine-to-machine — explicit organization_client_grant required per Organization; allow_any_organization is not available for third-party applications.
3. Org-scoped consent — user grants are now scoped to (application, API, scopes, org_id). Consent in one Organization does not carry over to another.
4. XAA bypass — deliberately not documented in this release; will be added when Cross-App Access ships.

Scope

New article:

• manage-users/organizations/configure-organizations/enable-third-party-application-access.mdx — the canonical how-to for an Organization admin enabling third-party access, with Dashboard and Management API tabs.

Updated articles (19 total):

• Third-party applications section (8): parent overview, first-party-and-third-party-applications, security-controls, configure-third-party-applications, user-consent-and-third-party-applications, troubleshooting, permissive-mode, and the migration guide.
• Organizations section (5): organizations-overview, using-tokens, configure-organizations (index), login-flows-for-organizations, custom-development.
• M2M Organizations section (5): parent overview, configure-your-application-for-m2m-access, authorize-m2m-access, revoke-m2m-access, audit-m2m-access.
• Sidebar: config/navigation/manage-users.json.

Editorial decisions

• No permissive references in manage-users/organizations: third-party applications are referred to as a single concept across the Organizations section. Permissive-specific differences are confined to permissive-mode.mdx.
• XAA deferred: no placeholder text or "coming soon" notes in any article.

Placeholders for follow-up

The following are flagged in-line with {/* TODO: ... */} markers and need to be filled before publication:

• Screenshots (4): Organization Settings page with the third_party_client_access toggle, close-up of the toggle, and a paired set of org-scoped consent dialogs (same user, same app, two Organizations) for the consent article.
• API examples (3): full AuthCodeGroup-wrapped example for /authorize with organization in the configure article; GET /api/v2/organizations/{id} showing the new property in the new how-to article; sample access_denied error response body for the troubleshooting entry.

References

• Confluence script (full per-article spec, screenshot/API inventory, working split): Documentation Approach: Third-Party Applications with Organizations
• Roadmap ticket: ROAD-5837 — Third Party Apps GA: Extended Functionality

Testing

Build the site locally and verify rendering and content cd main & mintlify dev

Checklist

• I've read and followed CONTRIBUTING.md.
• I've tested the site build for this change locally.
• I've made appropriate docs updates for any code or config changes.
• I've coordinated with the Product Docs and/or Docs Management team about non-trivial changes.

[AlexJPotter]

Looks like this is an existing issue but /docs/manage-users/organizations/configure-organizations/configure-organization-client-grants does not exist and you get a 404 when you hit this link.

It looks like docs/manage-users/organizations/organizations-for-m2m-applications/authorize-m2m-access might be the page we want to target here.

[AlexJPotter]

As I think has already been flagged, the UI currently shows "Third-Party Client Access" as the section name rather than "Third-Party Application Access".

enable the toggle

The actual UI as implemented at present is a radio group, not a toggle, with two options:

• "Block Third-Party Client Access"
• "Allow Third-Party Client Access"

The "Client" vs "Application" wording obviously needs updating here as well, but we should align this documentation with the fact that it's multiple options rather than a single toggle 👍

[AlexJPotter]

If it helps, I hit this endpoint with one of my own Organizations and the response looked like this:

{
  "id": "org_9lBHW9jzd0tQWPFH",
  "name": "acme",
  "display_name": "ACME Corporation",
  "third_party_client_access": "allow"
}

[AlexJPotter]

Is there any reason we're pushing "Pre-Login" organization discovery here?

Note that "Prompt for Organization" encapsulates two possible modes: the user enters the organization name, or the user enters their organization email. So the first bullet here is the general approach, while the second bullet point here is a specific option within that approach - I think it could be a bit confusing for folks to have it laid out like this.

Furthermore, what's wrong with the "Post-Login" ("Prompt for Credentials") organization discovery flow? i.e. the user logs in first and then we show an organization picker with all the organizations they belong to that support 3P clients? Unless I'm mistaken, this approach solves the same problem, and only "No Prompt" is problematic.

If the idea here is to explain the two options that are available to ensure an organization is picked during login, then I think we should present "Prompt for Organization" and "Prompt for Credentials" as the two options, and not get too much down into the weeds of requiring verified organization domains etc. for the specific sub-option of the "Prompt for Organization" flow (probably better to just link out to the docs/manage-users/organizations/login-flows-for-organizations#configure-the-login-flow-for-your-application page and let that do the heavy lifting).

[AlexJPotter]

nit: would it be better to link specifically to docs/manage-users/organizations/organizations-for-m2m-applications/authorize-m2m-access here? i.e. the page that talks about the authorization mechanisms?

[AlexJPotter]

See my other comments in this review where I've commented on similar passages

[AlexJPotter]

See my other comment talking about the actual error behaviour vs the access_denied documented here

[AlexJPotter]

The tip for the Management API link is wrong here - it looks like it's a copy-paste error.

Looking elsewhere, I think the tip should be:

"Management API: A product to allow customers to perform administrative tasks."

[AlexJPotter]

And again here - same comments as elsewhere

[AlexJPotter]

allow_any_organization is an M2M concept (which is the scope of this page), but the link we're pointing to here is about enabling third-party application access in user flows, not about organization client grants. We should change the link to point at the docs/manage-users/organizations/organizations-for-m2m-applications/authorize-m2m-access page instead.