docs(ai-agents): add OAuth credential override documentation

[Ian Alton (ian-at-airbyte)]

What

Documents the OAuth credential override feature introduced in airbytehq/sonar#2587, which allows organizations to replace Airbyte-managed OAuth app credentials with their own via configure_oauth_app_parameters(). Addresses airbytehq/airbyte-internal-issues#15826 (item 4).

How

Updates docs/ai-agents/platform/authenticate/build-auth/build-your-own.md:

• Wraps the existing Part 1 curl example in <Tabs> to add a Python SDK tab alongside the existing API tab.
• Adds a new "Removing an override" subsection with both SDK (credentials=None) and API (DELETE endpoint) examples.

Review guide

1. docs/ai-agents/platform/authenticate/build-auth/build-your-own.md — The <Tabs> / <TabItem> components rely on imports already present at the top of the file. Verify the Python SDK examples use correct model names (e.g. HubspotOAuthCredentials) that match what airbytehq/sonar#2587 generates.

Review checklist

• Verify <Tabs> imports exist at top of build-your-own.md (should already be there from existing content).
• Confirm configure_oauth_app_parameters() API and model names match the sonar PR implementation.
• Check that the "Removing an override" section's DELETE endpoint path matches the actual API.

User Impact

Users following the "Build your own OAuth flow" guide can now see Python SDK examples alongside curl, and learn how to remove an override. Previously, only curl examples existed and the removal flow was undocumented.

Can this PR be safely reverted and rolled back?

• YES 💚

Updates since last revision

• Removed the OAuth credential override section from tutorial-hosted.md per review feedback — keeping the quickstart as simple as possible.
• Removed the "With your own OAuth app credentials" section from hosted.md per review feedback — this feature belongs exclusively on the "Build your own OAuth flow" page.

---

Link to Devin run: https://app.devin.ai/sessions/fe1e9e0ab40a43488b60419db5daf417
Requested by: Ian Alton (@ian-at-airbyte)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /bump-progressive-rollout-version - Bumps connector version with an RC suffix (2.16.10-rc.1) for progressive rollouts (enableProgressiveRollout: true).
    • Example: /bump-progressive-rollout-version changelog="Add new feature for progressive rollout"
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
  • /bump-bulk-cdk-version bump=patch changelog='foo' - Bump the Bulk CDK's version. bump can be major/minor/patch.
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.

[github-actions]

Deploy preview for airbyte-docs ready!

✅ Preview
https://airbyte-docs-i0hjx0938-airbyte-growth.vercel.app

Built with commit fe66b9c.
This pull request is being automatically deployed with vercel-action

[Ian Alton (ian-at-airbyte)]

On second thought, let's not document this on this page. I'd prefer to keep the quick start as quick and simple as possible. They have other ways to learn.

[devin-ai-integration]

Done — removed the OAuth section from the quickstart tutorial in c9a79bc.

---

Devin session

[Ian Alton (ian-at-airbyte)]

I'm kind of confused by the order of operations on /ai-agents/platform/authenticate/hosted. We show three options here:

• With API Tokens (API call only)
• With OAuth (API call only)
• With your own OAuth app (Python and API)

I don't think this is properly explained at a higher level, at least not for the SDK. What if I want to use the SDK for API/Oauth authentication without using my own OAuth app? Is that now possible? (IE there are 3 ways, with two complete options for each way, SDK and API)?

[devin-ai-integration]

Good point — the three subsections are actually mixing two different concerns:

1. "With API tokens" and "With OAuth credentials" are about creating a connector (storing end-user credentials).
2. "With your own OAuth app credentials" is about configuring which OAuth app identity is used — it's an org-level setting that happens before connector creation.

So the new section isn't really a third "way to create a connector" — it's an orthogonal configuration step. That probably explains the confusion.

A few options for how to fix this:

A) Move the OAuth app override section out of "Creating connectors with credentials" into its own top-level heading (e.g. between "Creating connectors with credentials" and "Security considerations"), since it's a separate operation.

B) Add a brief intro paragraph under "Creating connectors with credentials" explaining the two auth methods (tokens vs OAuth), then keep the OAuth app override as a subsection but add a note that it's an optional org-level configuration, not a third auth method.

C) Add Python SDK examples to the first two sections as well, so all three are consistent. (Though I'm not sure the SDK currently has a direct equivalent for the connector-creation curl calls — I'd need to check.)

Which direction do you prefer? Happy to implement whichever approach you think reads best.

---

Devin session

[Ian Alton (ian-at-airbyte)]

OK, so my confusion makes sense to me now. We actually don't want to talk about this at all on the main auth page. We already reference building your own OAuth flow from there. If I understand correctly, it makes the most sense to JUST update the "Build your own OAuth flow" page, right? I can't think of another context in which you would use this.

[devin-ai-integration]

Makes sense — removed the entire section from hosted.md. The PR now only updates build-your-own.md (adding Python SDK tabs to Part 1 and a "Removing an override" subsection).

---

Devin session

[Ian Alton (ian-at-airbyte)]

/ai-docs-review

AI Docs Review Skipped

No connector changes detected in this PR. Documentation review is only triggered for PRs that modify connector code.

[Aldo Gonzalez (aldogonzalez8)]

APPROVED