n8n:node add oauth

Engineering Community

Skill notes

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:

Step 1 — Explore the node

Read the following (adjust path conventions for the specific service): 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

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

Step 3 — Create the credential file

File: packages/nodes-base/credentials/{NODE_NAME}OAuth2Api.credentials.ts 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

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@n8n-io · no license declared
Token usage
Lean
Setup complexity
Manual integration
External API key
Required · Vendor-specific
Operating systems
macOS · Linux · Windows
Runtime requirements
Node.js
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
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:

02
Step 1 — Explore the node

Read the following (adjust path conventions for the specific service): 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

03
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

04
Step 3 — Create the credential file

File: `packages/nodes-base/credentials/{NODE_NAME}OAuth2Api.credentials.ts` 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

05
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):

06
Step 5 — Update GENERICOAUTH2CREDENTIALSWITHEDITABLESCOPE (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.

07
Step 6 — Update GenericFunctions.ts

Step 6 — Update GenericFunctions.ts

08
Step 7 — Update the node file(s)

Step 7 — Update the node file(s)

09
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: Metadata — name, extends array, `enabledScopes` default, auth URL, token URL,

10
Step 9 — Update GenericFunctions.test.ts

In the credential-routing `describe` block: If a site-ID cache (`_cloudIdCache`) was added, import it and call `_cloudIdCache.clear()` (or equivalent) in `afterEach`. Add/update the OAuth2 routing test case: Simple routing: assert `getCredentials` was called with the correct credential

11
Step 10 — Verify

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

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.