n8n 템플릿이 사용자에게 API 키를 요청하도록 하세요

Source: Dev.to

당신은 공유할 가치가 있는 워크플로우를 만들었고, 그것은 완벽하게 동작합니다. 하지만 누군가가 그것을 가져가면 문제가 생깁니다.

핵심은 API 키입니다. 당신의 키를 사용하면 모든 사용자가 당신의 계정으로 청구되고, 그들의 키를 사용하면 각 사용자가 자격 증명 UI를 찾아 키를 붙여넣고 매번 다시 연결해야 합니다. 두 경우 모두 마찰이 발생합니다. 더 깔끔한 방법은 워크플로우가 폼에서 키를 요청하도록 하고, 그 값을 HTTP 노드에 전달하는 것입니다. 생각보다 간단합니다.

이 글에서는 작동하는 자격 증명 설정을 통한 패턴, 단일 노드 간단 사례를 위한 대안, 주의할 점, 그리고 커스텀 노드 제작자에게 제공되는 기능에 대해 설명합니다.

아래 스크린샷은 n8n에 내장된 Bearer Auth 자격 증명과 n8n-nodes-ldxhub 패키지의 자체 자격 증명 스키마에서 가져온 것입니다. 이 기법 자체는 일반적이며, 여기서 보여지는 내용은 모든 HTTP‑node 워크플로우와 표현식 모드 자격 증명을 지원하는 모든 커스텀 노드에 적용됩니다.

폼이 물어보고, 자격 증명이 듣는다

가장 간단한 경우: Form Trigger가 API 키를 수집하고, HTTP 노드가 해당 키로 인증된 엔드포인트에 요청을 보냅니다. 두 노드 사이에 다리 역할을 하는 것이 하나 있는데, 이 다리는 직접적인 표현식이 아니라 자격 증명을 통해 동작합니다.

흐름

• Form Trigger가 api_key를 수집합니다 (Password 요소 타입을 사용해 마스킹)

• Bearer Auth 자격 증명이 해당 폼 입력을 표현식으로 참조합니다

• HTTP 노드가 자격 증명을 사용합니다

Form Trigger 설정은 간단합니다. 필드를 하나 추가하세요:

Form Trigger
  Form Fields:
    - Label: API Key
    - Element Type: Password
    - Custom Field Name: api_key
    - Required Field: yes

Element type이 중요합니다. Text 대신 Password를 사용하면 화면에 입력값이 마스킹되어 브라우저를 힐끗 보는 사람에게 키가 보이지 않게 됩니다.

사용자가 워크플로우 URL을 열었을 때 보게 되는 렌더링된 폼은 다음과 같습니다:

자격 증명을 표현식 모드에 연결하기

대부분의 최신 API가 사용하는 Bearer 토큰을 위해, Bearer Auth 타입의 새 자격 증명을 생성합니다. Authorization: Bearer … 헤더 전용으로 n8n에 내장된 일반 자격 증명입니다. 필드는 하나뿐입니다:

Bearer Token: YOUR_API_KEY

Bearer Token 필드 옆에 있는 작은 fx(또는 =) 토글을 클릭해 표현식 모드로 전환합니다. 그런 다음 값을 폼 입력을 가리키는 표현식으로 교체합니다:

Bearer Token: ={{ $('On form submission').item.json.api_key }}

= 접두사는 n8n에 이것이 문자열이 아니라 표현식임을 알려줍니다. {{ }} 안의 내용은 JavaScript이며, $('Node Name').item.json.field는 워크플로우 전체를 뒤져 다른 노드의 값을 가져옵니다—Implementation notes #001에서 소개한 긴 형태의 참조 패턴과 동일합니다. Bearer Auth 자격 증명은 전송 시 자동으로 토큰 앞에 Bearer를 붙여 주므로 직접 접두사를 작성할 필요가 없습니다.

자격 증명을 저장하면 다음과 같은 메시지가 보입니다:

[ERROR: No path back to node]

이는 표시 전용 메시지입니다. 자격 증명 편집 UI에는 워크플로우 실행 컨텍스트가 없기 때문에 현재 시점에 표현식을 해석할 수 없습니다. 나중에 실행 중인 워크플로우의 HTTP 노드가 이 자격 증명을 호출하면 표현식이 올바르게 해석됩니다.

많은 사람이 여기서 멈추는 이유는 이 메시지를 보고 자격 증명이 깨졌다고 생각하기 때문입니다. 실제로는 깨지지 않았습니다. 그대로 저장하고 워크플로우를 실행하면 키가 정상적으로 흐릅니다.

오류 텍스트에 대한 참고: 동일한 상황에서도 자격 증명 종류에 따라 표시되는 메시지가 약간씩 다릅니다. Bearer Auth는 [ERROR: No path back to node]를, 일부 커스텀 노드 자격 증명은 [ERROR: Referenced node doesn't exist]를 표시합니다. 원인은 동일합니다(디자인 시점에 워크플로우 컨텍스트가 없음)이며, 둘 다 런타임에서는 사라지는 무해한 메시지입니다.

자격 증명 타입 선택에 대한 참고: Bearer Auth는 표준 Authorization 헤더를 사용합니다. 대상 API가 다른 헤더 이름(X-API-Key, X-Custom-Auth 등)을 요구한다면 Header Auth(커스텀 Name/Value) 또는 Custom Auth(전체 JSON 형태 헤더)를 대신 사용하세요. 표현식 모드 기법은 모든 경우에 동일하게 동작합니다.

HTTP 노드에서 자격 증명 사용하기

HTTP Request 노드를 다음과 같이 설정합니다:

HTTP Request
  Authentication:    Generic Credential Type
  Generic Auth Type: Bearer Auth
  Credential:        
  Method:            (API에 맞는 메서드)
  URL:               (엔드포인트)

이제 HTTP 노드는 폼에서 입력된 값을 사용해 Authorization: Bearer … 헤더를 전송합니다. 하드코딩된 키가 없고, 사용자마다 별도의 자격 증명을 설정할 필요도 없습니다. 워크플로우가 물어보고, 사용자가 입력하고, 요청이 전송됩니다.

필요한 만큼 많은 HTTP 노드를 추가할 수 있습니다—모든 노드가 동일한 자격 증명을 참조하므로, 폼에 한 번만 키를 입력하면 하위 엔드포인트가 몇 개이든 동일하게 사용할 수 있습니다.

대안: 자격 증명 완전 생략

HTTP 노드가 하나뿐인 워크플로우라면 이 과정을 생략할 수 있습니다. HTTP 노드의 Authentication을 None으로 설정하고 헤더를 직접 작성합니다:

HTTP Request
  Authentication: None
  Headers:
    - Name:  Authorization
    - Value: =Bearer {{ $('On form submission').item.json.api_key }}

이 방법도 동작합니다. 설정이 더 빠르므로 알아두면 좋습니다.

하지만 다음과 같은 장점은 얻을 수 없습니다:

• 동일 워크플로우 내 여러 HTTP 노드에서 재사용 가능
• 자격 증명을 기대하는 커스텀 노드와의 연계 경로
• “인증 자료”와 “요청 데이터”를 구분하는 사고적 분리

프로토타입이나 일회성 테스트에는 충분합니다. 인증 호출이 하나 이상인 공개 템플릿이라면 자격 증명 방식을 사용하는 것이 확장성이 좋습니다.

주의해야 할 세 가지 사항

1. 표시 전용 오류 메시지는 자격 증명 타입마다 다르게 나타납니다

앞서 언급했듯이, 자격 증명 편집 UI에는 실행 컨텍스트가 없기 때문에 디자인 시점에 표현식을 해석할 수 없습니다. 저장하고 워크플로우를 실행하면 표현식이 정상적으로 해석됩니다. 중요한 점은 오류 메시지 자체가 자격 증명 타입에 따라 다르다는 것입니다:

• Bearer Auth, Header Auth, 대부분의 일반 자격 증명: [ERROR: No path back to node]
• 일부 커스텀 노드 자격 증명(예: 아래 LDX hub Dynamic credential): [ERROR: Referenced node doesn't exist]

두 경우 모두 표시 전용이며, 런타임에서는 사라집니다. 메시지 차이에 속아 특정 자격 증명 타입이 더 깨졌다고 판단하지 마세요.

실제 오타(표현식 안에 잘못된 노드 이름)를 입력하면 디자인 시점에도 같은 오류 메시지가 나타나지만, 원인은 다