N8n:node Add OAuth

Overview

Add OAuth2 (Authorization Code / 3LO) support to an existing n8n node. Works for any third-party service that supports standard OAuth2.

Before starting, read comparable existing OAuth2 credential files and tests under packages/nodes-base/credentials/ to understand the conventions used in this codebase (e.g. DiscordOAuth2Api.credentials.ts, MicrosoftTeamsOAuth2Api.credentials.ts).

Step 0 — Parse arguments

Extract:

• NODE_NAME: the service name (e.g. GitHub, Notion). Try to infer from the argument; if ambiguous, ask the user.
• CUSTOM_SCOPES: whether the credential should support user-defined scopes. If the argument does not make this clear, ask the user before proceeding:

  “Should users be able to customise the OAuth2 scopes for this credential, or should scopes be fixed?”

Step 1 — Explore the node

Read the following (adjust path conventions for the specific service):

1. Node directory: packages/nodes-base/nodes/{NODE_NAME}/
   • Find *.node.ts (main node) and any *Trigger.node.ts
   • Find GenericFunctions.ts (may be named differently)
   • Check if an auth / version subdirectory exists
2. Existing credentials: packages/nodes-base/credentials/ — look for existing {NODE_NAME}*Api.credentials.ts files to understand the naming convention and any auth method already in use.
3. package.json at packages/nodes-base/package.json — find where existing credentials for this node are registered (grep for the node name).

Step 2 — Research OAuth2 endpoints

Look up the service’s OAuth2 documentation:

• Authorization URL
• Access Token URL
• Required auth query parameters (e.g. prompt=consent, access_type=offline)
• Default scopes needed for the node’s existing operations
• Whether the API requires a cloudId / workspace ID lookup after the token exchange (Atlassian-style gateway APIs do; most services don’t)

If you can’t determine the endpoints confidently, ask the user to provide them.

Step 3 — Create the credential file

File: packages/nodes-base/credentials/{NODE_NAME}OAuth2Api.credentials.ts

import type { ICredentialType, INodeProperties } from 'n8n-workflow';

const defaultScopes

Rules:

• No authenticate block — oAuth2Api machinery handles Bearer token injection automatically.
• No test block — the OAuth dance validates the credential.
• defaultScopes at module level is the single source of truth: it populates both the enabledScopes default and the scope expression fallback. Update it in one place.
• If the service needs a domain / workspace URL for API call construction, add it as a visible string field before the hidden fields.

Step 4 — Register the credential in package.json

File: packages/nodes-base/package.json

Find the n8n.credentials array and insert the new entry near other credentials for this service (alphabetical ordering within the service’s block):

"dist/credentials/{NODE_NAME}OAuth2Api.credentials.js",

Step 5 — Update GENERIC_OAUTH2_CREDENTIALS_WITH_EDITABLE_SCOPE (custom scopes only)

Only do this step when CUSTOM_SCOPES = yes.

File: packages/cli/src/constants.ts

Add '{camelCase}OAuth2Api' to the GENERIC_OAUTH2_CREDENTIALS_WITH_EDITABLE_SCOPE array. Without this, n8n deletes the user’s custom scope on OAuth2 reconnect.

export const GENERIC_OAUTH2_CREDENTIALS_WITH_EDITABLE_SCOPE = [
	'oAuth2Api',
	'googleOAuth2Api',
	'microsoftOAuth2Api',
	'highLevelOAuth2Api',
	'mcpOAuth2Api',
	'{camelCase}OAuth2Api', // ← add this
];

Step 6 — Update GenericFunctions.ts

6a — Standard services (token works directly against the instance URL)

Add an else if branch before the existing else fallback:

} else if ({versionParam} === '{camelCase}OAuth2') {
	domain = (await this.getCredentials('{camelCase}OAuth2Api')).{domainField} as string;
	credentialType = '{camelCase}OAuth2Api';
} else {

6b — Gateway services requiring a workspace/cloud ID lookup

When the OAuth token is scoped for a gateway URL rather than the direct instance URL (Atlassian’s api.atlassian.com is the canonical example), add a module-level cache and lookup helper before the main request function:

// Module-level cache: normalised domain → site/cloud ID
export const _cloudIdCache = new Map<string, string>();

async function getSiteId(
	this: IHookFunctions | IExecuteFunctions | ILoadOptionsFunctions,
	credentialType

Then in the main request function:

} else if ({versionParam} === '{camelCase}OAuth2') {
	const rawDomain = (await this.getCredentials('{camelCase}OAuth2Api')).domain as string;
	credentialType = '{camelCase}OAuth2Api';
	const siteId = await getSiteId.call(this, credentialType, rawDomain);

The existing uri: \${domain}/rest${endpoint}`` construction then produces the correct gateway URL automatically.

Add NodeOperationError to the n8n-workflow import if not already present.

Step 7 — Update the node file(s)

Main node (*.node.ts)

Credentials array — add an entry for the new credential type:

{
	name: '{camelCase}OAuth2Api',
	required: true,
	displayOptions: { show: { {versionParam}: ['{camelCase}OAuth2'] } },
},

Version/auth options — add to the {versionParam} (or equivalent) options list:

{ name: '{Display Name} (OAuth2)', value: '{camelCase}OAuth2' },

Keep default unchanged — existing workflows must not be affected.

Trigger node (*Trigger.node.ts, if present)

Same two changes. Preserve any displayName label pattern already used by other credential entries in that trigger node’s credentials array.

Step 8 — Write credential tests

File: packages/nodes-base/credentials/test/{NODE_NAME}OAuth2Api.credentials.test.ts

Use ClientOAuth2 from @n8n/client-oauth2 and nock for HTTP mocking. Follow the structure in MicrosoftTeamsOAuth2Api.credentials.test.ts.

Required test cases:

1. Metadata — name, extends array, enabledScopes default, auth URL, token URL, authQueryParameters default (if applicable).
2. Default scopes in authorization URI — call oauthClient.code.getUri(), assert each default scope is present.
3. Token retrieval with default scopes — mock the token endpoint with nock, call oauthClient.code.getToken(...), assert token.data.scope contains each scope.
4. Custom scopes in authorization URI (skip when CUSTOM_SCOPES = no).
5. Token retrieval with custom scopes (skip when CUSTOM_SCOPES = no).
6. Minimal / different scope set (skip when CUSTOM_SCOPES = no) — assert scopes not in the set are absent from both the URI and token response.

Lifecycle hooks required:

beforeAll(() => { nock.disableNetConnect(); });
afterAll(() => { nock.restore(); });
afterEach(() => { nock.cleanAll(); });

Step 9 — Update GenericFunctions.test.ts

In the credential-routing describe block:

1. If a site-ID cache (_cloudIdCache) was added, import it and call _cloudIdCache.clear() (or equivalent) in afterEach.
2. Add/update the OAuth2 routing test case:
   • Simple routing: assert getCredentials was called with the correct credential name and requestWithAuthentication was called with the correct name and URI.
   • Gateway lookup: mock requestWithAuthentication to return the accessible-resources payload on the first call and {} on the second. Assert the first call targets the resources endpoint and the second call uses the gateway base URL with the site ID.

Step 10 — Verify

# From packages/nodes-base/
pnpm test credentials/test/{NODE_NAME}OAuth2Api.credentials.test.ts
pnpm test nodes/{NODE_NAME}/__test__/GenericFunctions.test.ts
pnpm typecheck
pnpm lint

# Only when constants.ts was changed:
pushd ../cli && pnpm typecheck && popd

Fix any type errors before finishing. Never skip pnpm typecheck.