Add AI Pass to an existing BYOK app without replacing it

An existing BYOK app does not need a payment-system rewrite to offer AI Pass. It needs a clear additional choice and a careful boundary around what changes.

Keep the current provider route for customers who want it. Add wallet-funded OAuth for customers who would rather connect AI Pass than manage supported provider keys. Preserve the app's accounts, subscriptions, data, and hosting unless there is a separate, explicit reason to change them.

This is a routing and product-design decision. It should not become a surprise migration for everyone who already uses the app.

Decide what each connection means

Consider a fictional research notebook called Margin Notes. It already lets users supply a provider key to summarize saved articles. Users sign in with the notebook's own account system, and some pay for a larger document library.

A direct-provider connection means the selected provider account funds the relevant inference requests. An AI Pass connection means supported requests use the user's AI Pass wallet through the documented authorization path. Neither connection decides who owns a notebook or whether its owner has purchased extra storage.

Recommended settings copy:

AI payment source

Provider account: keep using your supported provider key.

AI Pass wallet: connect AI Pass to fund supported AI requests without sharing provider keys.

Changing this setting does not change your Margin Notes subscription.

That last line belongs in the implementation as well as the copy. Review the existing auth and billing reference before modifying a product with established accounts or credits.

Keep the choice close to the request

A settings toggle alone is too easy to forget. Near "Summarize article," show the currently selected payment source. If the user changes routes, explain any meaningful difference in model availability or behavior before sending the next request.

Do not silently fall back from an unavailable provider key to AI Pass. That can change the billing relationship and spend a wallet balance the user did not intend to use. The reverse fallback is equally problematic.

A useful failure message is:

This request could not use your selected provider connection. Your article is saved. Retry this connection or choose AI Pass before starting a new request.

The message should not assert why the provider failed unless the actual error supports that diagnosis. It should also distinguish an action that never started from one whose outcome is uncertain, so a retry does not casually duplicate paid work.

Choose integration shape around the existing app

If Margin Notes has a suitable browser surface, the SDK documentation describes the browser path. If generation runs server-side with private prompts or data, or the product's security policy forbids browser token custody, use backend OAuth with the REST documentation.

Do not weaken a content security policy merely to fit a preferred demo. Do not put runtime credentials into public configuration. Follow the documented path rather than asking a coding assistant to invent authentication helpers that sound plausible.

The canonical integration guide starts by inspecting current AI entry points, user sessions, billing, and deployment. That inspection is especially useful here: an app may have more than one generation route, including background jobs that the main button does not exercise.

Keep the same app identity and existing deployment. AI Pass Spaces is optional hosting for suitable cases, not a prerequisite for using the wallet or gateway.

Roll out one visible action first

Start with article summarization rather than switching every AI feature simultaneously. Add the wallet route behind an explicit user choice, preserve the direct route, and leave existing stored documents untouched.

A practical acceptance exercise uses separate account states. A provider-connected user should still summarize through the provider. A wallet-connected user should be able to authorize the selected paid action through the real flow. A disconnected user should see a connection choice without losing the article. A paying subscriber should retain purchased storage regardless of which AI source is selected.

These are proposed checks, not claims that an integration has already passed them. Build success alone proves none of the wallet billing behavior. Verify a real wallet-funded request only with the user's approval for that paid action and its cost basis when available.

Afterward, confirm that one deliberate action produced one request, the real result reached the notebook, and reconnecting does not erase the user's work. Investigate failures before enabling the route more widely.

Let customers keep a reasoned preference

Provider-direct access may be a requirement for an organization. AI Pass may be preferable for someone who wants wallet-based access across participating apps without managing provider credentials. Supported models, pricing, and contractual requirements can differ, so avoid promising exact equivalence.

Offer both honestly when the product can support both well. If a customer chooses provider-direct access, respect that choice instead of repeatedly reopening the wallet pitch. A successful addition leaves existing customers comfortable and gives new customers another understandable way to start summarizing.