OAuth2 in n8n: Configure and Test an External Integration

OAuth2 in n8n can authorize a workflow to access an external service when that provider supports the arrangement. Configuration depends on the accepted grant, authorization and token endpoints, client identity, callback, and scopes. There are no universal values to paste into every integration.

Use the provider’s documentation together with the callback shown by the actual n8n credential. Do not confuse this connection with n8n’s own administrative API, which uses a separately documented API-key mechanism.

Identify the authorization flow the provider supports

In an authorization-code arrangement, a person authorizes access through the provider and the client exchanges a code for tokens. Client credentials applies to supported machine-to-machine arrangements rather than access on behalf of a user.

The HTTP Request credential guide describes available authentication options. Select the grant the destination supports for the account and resource, not whichever form looks shorter.

Access-token lifetime, refresh behavior, rotation, and revocation depend on the provider. A first successful connection does not establish that the credential will remain usable indefinitely.

Gather the provider’s configuration before opening fields

Confirm API availability, authorization and token URLs for the correct environment, required scopes, and any administrator approval. Identify which application registration belongs to this integration.

Copy the callback displayed by n8n exactly into the provider’s allowed redirect configuration. Scheme, hostname, port, path, and trailing slash can matter. Do not substitute a browser address you happen to have open.

Use a purpose-specific client and distinguish development from production. If app verification or administrative consent is required, treat it as a real dependency rather than searching for an undocumented route around the provider’s policy.

Keep each configuration item understandable

Use the appropriate credential type

Where available, inspect a predefined credential for the service before constructing a generic one. It can reduce configuration work, but still verify the requested account and access.

For a generic OAuth2 credential, fill the documented fields for the selected grant. The n8n reference distinguishes authorization-code and client-credentials settings, including the provider’s expected client-authentication method.

Keep secrets in protected credentials rather than ordinary node data, code, or pinned examples. A client secret should not be copied into an operational checklist to make future setup easier.

Read the consent screen before completing authorization

Use an appropriate test account and inspect the application name, selected identity, and requested access. If unrelated administration, files, or contacts appear, pause to review the scope.

Authorization should correspond to the operation already defined. A workflow needing a narrow lookup should not acquire broad account access simply because a default setting requested it.

Record the app owner and purpose without preserving tokens or private session links. Screenshots used for support should omit secrets and unnecessary account information.

Test one small read operation

Call a documented read endpoint with non-sensitive data and inspect both the response and its business meaning. Confirm that the returned resource belongs to the intended account.

Distinguish transport, request, authentication, and authorization errors. A missing or expired token, insufficient permission, invalid grant, mismatched redirect, and pending consent are not interchangeable diagnoses.

Retain the sanitized status and message. Do not copy the complete authorization header or token response into a public issue. A useful support record explains the failing stage and the relevant configuration category without exposing the credential.

Verify renewal and revocation in a controlled environment

Do not assume a refresh token exists. Providers may have specific issuance requirements, lifetimes, rotation rules, or limits. Check those rules and the client’s actual supported behavior.

Test an appropriate expiration or revocation case outside the live business path. Establish whether the workflow renews access, requests another authorization, or stops and alerts an owner.

A refresh failure should not trigger unbounded repetitions of a state-changing operation. Separate repairing authorization from deciding whether the original business action already happened.

Keep OAuth separate from n8n administration

The public n8n API documentation requires X-N8N-API-KEY authentication. That administrative key is not the OAuth token for an external CRM or cloud service.

Draw the caller, n8n, authorization service, and target API. Mark which service issues each token and which request uses it. This often reveals that a credential has been placed in the wrong connection.

For an administrative inventory, use the public-API inventory guide. Do not add instance administration to an external-service workflow that does not need it.

Control use, sharing, and credential replacement

Restrict who can edit or use the credential according to the available project and role controls. Access to a workflow should not be treated as permission to distribute the secrets behind it.

Keep development and production credentials distinct. When the responsible person changes or exposure is suspected, coordinate provider-side revocation and the replacement in n8n. Deleting a value from one node does not revoke a token still valid at the provider.

Plan replacement in a controlled window. Uncoordinated rotation can interrupt work too. Inspect exports, backups, proxy logs, and execution data for places where authorization material should not have been retained.

Define readiness beyond the first connection

Confirm the supported grant, exact redirect, minimum scopes, appropriate consent, successful read, expected denial, known renewal behavior, alert owner, and revocation route.

Before introducing a write, use an authorized test resource and check duplicate behavior and recovery. A green credential indicator is not proof that the destination received the intended change or that a repeated request is harmless.

Maintain a manual alternative for important work that cannot wait for a personal account owner to reauthorize. Document the supported process instead of leaving the team dependent on an unexplained browser session.

Example: a read-only customer lookup

Suppose the workflow needs one approved customer’s status. Define the endpoint and required access, authorize the dedicated test connection, and confirm that the sample response contains only the necessary fields.

Then inspect what happens when permission is absent or revoked. The useful completion evidence includes both the permitted lookup and an understood failure route. It does not include sending a real customer message just because the integration also offers that capability.

Before testing a write, confirm the account or organization returned by the successful lookup. A working token for the wrong tenant is still an incorrect connection. Keep that identity check in the acceptance record so later credential replacement does not silently change the destination.

Frequently asked questions

Is OAuth2 the same as an API key?

No. Use the mechanism documented for the specific service and keep the two credentials separate.

Can I choose any grant?

Only a flow supported by the provider and appropriate to the account and resource.

Will n8n always renew the token?

Do not assume that. Verify provider rules, token issuance, rotation, and the actual credential behavior.

Which callback should I register?

The redirect URI displayed by the n8n credential, entered exactly into the provider’s authorized configuration.