feat(core): Add configurable HTTP status code for OAuth2 token refresh

[guillaumejacquart]

Summary

• Added support for configurable HTTP status codes to trigger OAuth2 token refresh.
  • Previously, only 401 was checked.
  • This PR allows users to specify custom status codes (e.g., 403) that indicate token expiration for APIs that return non-standard codes.
• Extracted duplicate token refresh logic into a shared helper and added comprehensive unit tests covering the new behavior.

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/IAM-36

Review / Merge checklist

• PR title and summary are descriptive
• Tests included (4 new unit tests for token refresh behavior)
• Docs updated or follow-up ticket created
• PR Labeled with release/backport (if the PR is an urgent fix that needs to be backported)

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...xecution-context/utils/request-helper-functions.ts	75.00%	8 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

No issues found across 4 files

Architecture diagram

sequenceDiagram
    participant Node as Node Execution Engine
    participant Creds as Credential Store
    participant API as External API
    participant OAuth as OAuth2 Provider
    participant DB as Database (CredentialsHelper)

    Note over Node, API: Initial Request Flow

    Node->>Creds: getCredentials()
    Creds-->>Node: OAuth2 Data (incl. NEW: tokenExpiredStatusCode)

    Node->>Node: NEW: resolveTokenExpiredStatusCode()
    Note right of Node: Priority: Credential Config > Node Options > 401

    Node->>API: httpRequest() with Access Token

    alt Success (2xx)
        API-->>Node: Data
    else CHANGED: Response Status == tokenExpiredStatusCode
        API-->>Node: Error (e.g., 403 Forbidden)
        
        Note over Node, OAuth: NEW: centralized refreshOrFetchToken flow
        
        Node->>OAuth: Request new token (Refresh or Client Credentials)
        OAuth-->>Node: New Access Token + Refresh Token

        Node->>DB: updateCredentialsOauthTokenData()
        DB-->>Node: Persisted

        Node->>API: Retry httpRequest() with New Token
        API-->>Node: Data
    else Other Error Status
        API-->>Node: Error Response
        Node-->>Node: Throw ApplicationError
    end

Loading