Skip this page if every credential your agents need is an API key or basic auth — those go straight to the platform's own encrypted storage and need none of it.
OAuth is different. The platform does not implement OAuth: Nango does, and the platform holds a reference to a Nango connection. That means three systems have to agree before a customer can click Connect — the provider, Nango, and the platform — and each one holds a piece the others need.
Provider (e.g. Google Cloud) Nango CXP Platform
───────────────────────────── ───────────────────── ──────────────────────
OAuth app Integration Credential requirement
client id + secret ──────→ client id + secret
authorized redirect URI ←────── callback URL
scopes ──────→ scopes
unique key ──────→ Integration ID
connection ←────── Connect UI
The join that matters, and the one nothing tells you: Nango's integration "unique key" is exactly what you type into the platform's Integration ID field. Get that wrong and everything else looks configured while nothing works.
You need a Nango environment already wired to the platform — that is step 3 of Platform setup. This page is what goes inside it.
1. Register an OAuth app with the provider
Every OAuth provider needs an app registered in its own developer console, and the details differ per provider — Nango publishes a page per integration with the specifics. Using Google as the example, because it is the strictest:
- Enable the specific API you need in Google Cloud (Gmail API, Drive API — whichever your agent will call). Enabling the wrong one produces a token that authenticates fine and is rejected by the API.
- Configure the OAuth consent screen, and under Data Access → Add or Remove Scopes add the scopes matching the APIs you enabled.
- APIs & Services → Credentials → Create Credentials → OAuth client ID, application type Web application.
- Under Authorized redirect URIs, add Nango's callback:
https://api.nango.dev/oauth/callbackfor Nango Cloud, or your own host's callback path if you self-host Nango. A mismatch here is the single most common failure, and the error appears on Google's screen rather than anywhere you control. - Copy the Client ID and Client Secret.
2. Create the integration in Nango
In the Nango dashboard, in the environment whose secret key the platform holds — Nango's keys are per environment, and an integration created in the wrong one is invisible to the platform:
- Integrations → Configure New Integration, and pick the API.
- Set the unique key. This is the identifier you will use on the platform. Pick something stable and descriptive; renaming it later breaks every credential requirement pointing at it.
- Paste the Client ID and Client Secret from step 1.
- Set the scopes.
Steps 1 and 2 are infrastructure — do them now, once per provider. The remaining two happen later in the walkthrough, after the agent exists; they are described here so the whole chain is in one place, and Credentials walks them properly.
3. Point a credential requirement at it (later, per agent)
This is where the two systems meet. On the agent, Credential Requirements → Add, credential type OAuth, and the Integration ID field becomes a dropdown listing the integrations in the linked Nango environment. Pick the one you made in step 2.
Two things that will confuse you if they are not said out loud:
If the OAuth option is greyed out with (Nango environment required), the agent has no Nango environment attached. Note that entering Nango credentials manually on the agent does not satisfy this — OAuth requires a shared Nango runtime environment selected on the agent record. Fix it in the agent's settings.
If Integration ID renders as a plain text box instead of a dropdown, the platform could not list integrations. That means one of: the secret key is wrong, the host URL is wrong, or the environment genuinely has no integrations. You can type a key by hand, and it will be accepted — the failure surfaces much later, when a customer tries to connect. Treat the text box as a diagnostic, not a convenience.
4. The customer connects (later, per customer)
A member opens the agent's Credentials page, picks the requirement, and clicks Connect. The platform creates a Nango connect session scoped to that one integration and opens Nango's Connect UI; the customer completes the provider's consent screen; the platform stores the resulting connection.
From then on the agent's runs receive that connection in connectionIds, and the task resolves it — see Credentials.
Token refresh is Nango's job and it is invisible to you. The platform stores no tokens and never refreshes anything; it asks Nango for the credential at resolve time and Nango returns a valid one. What the platform does do is listen for Nango's token-refresh-error webhook and mark the connection as errored — which is why the webhook setup in Platform setup matters. Without it, a connection that has gone stale looks healthy until a run fails.
Things that will bite
Testing mode expires refresh tokens after seven days. A Google OAuth app with an external user type in Testing mode issues refresh tokens that die after a week unless you requested only basic scopes. A scheduled agent works perfectly for seven days and then fails every run. Publish the app before anyone depends on a schedule — this is the single most common way an OAuth agent breaks in a way nobody predicted.
Restricted and sensitive scopes need Google's review. Reading a mailbox is a restricted scope, and restricted scopes require verification plus a third-party security assessment that takes weeks and costs money. Start it at the beginning of the project, not when you are ready to launch. If that is not viable, check whether a narrower scope clears the bar.
Scopes live in two places and must agree. The provider app and the Nango integration each carry a scope list. The consent screen shows what the provider app allows; the token carries what Nango asked for. A scope missing from either produces a token that works until it touches the endpoint that needed it.
Do not use the platform's "Override OAuth scopes" field. It exists on the credential form but does not do what its help text claims for the vast majority of providers — set scopes on the Nango integration instead.
Nango environments are per environment, in both systems. Nango's dev and prod environments have separate keys and separate integrations, and so do your platform runtime environments. Creating the integration in Nango prod while the platform holds a dev key produces an empty dropdown and no error.
Give each customer organization its own Nango environment. Connections live in the Nango environment, not in the platform org, and the platform's "pick an existing connection" list is scoped to the integration rather than to the org. Share one Nango environment across several customers and each customer's credential form can list the others' connections. One environment per org avoids it entirely, and also keeps a rotated Nango key from affecting every customer at once.
Who owns the OAuth app?
A decision, not a default, and worth making deliberately because it is awkward to reverse:
You own it. One app, one verification process, one consent screen showing your product's name. Customers connect without any setup of their own. You carry Google's review, and the app's quotas are shared across all customers.
The customer owns it. They register the app in their own console and supply the client id and secret; the credential form's OAuth overrides accept a per-connection client id and secret. Their consent screen, their verification, their quotas. This suits enterprise customers with their own security review, and it means one customer's problem with the provider cannot affect another's.
The platform supports either. It has no opinion, and there is no default it will apply for you.
Next
With the provider app and the Nango integration in place, create the agent that will use them: Create the agent.