n8n은 API 호출을 인증하기 위해 API 키를 사용합니다.
Note
기능 사용 가능 여부
n8n API는 무료 체험 기간 동안에는 사용할 수 없습니다. 이 기능을 이용하려면 업그레이드해 주세요.
API 키 생성#
- n8n에 로그인합니다.
- Settings > n8n API로 이동합니다.
- Create an API key를 선택합니다.
- Label을 선택하고 키의 Expiration(만료) 시간을 설정합니다.
- Enterprise 플랜을 사용 중이라면 키에 부여할 Scopes(범위)를 선택합니다. 사용 가능한 전체 범위 목록은 API Scopes를 참고하세요.
- My API Key를 복사하여 이 키로 호출을 인증하는 데 사용합니다.
키를 사용해 API 호출하기#
API 호출 시 X-N8N-API-KEY라는 이름의 헤더에 API 키를 담아 보냅니다.
예를 들어, 활성 상태인 모든 워크플로를 조회하고 싶다면 curl 요청은 다음과 같습니다.
# For a self-hosted n8n instance
curl -X 'GET' \
'<N8N_HOST>:<N8N_PORT>/<N8N_PATH>/api/v<version-number>/workflows?active=true' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: <your-api-key>'
# For n8n Cloud
curl -X 'GET' \
'<your-cloud-instance>/api/v<version-number>/workflows?active=true' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: <your-api-key>'
노드 구성#
워크플로 내에서 n8n API를 호출하려면 n8n node를 사용하세요. 자격 증명을 생성할 때 다음 필드를 입력합니다.
- API Key: Create an API key에서 생성한 키를 붙여넣습니다.
- Base URL: 다음 형식 중 하나로 인스턴스의 API 루트를 입력합니다.
- Cloud:
https://<name>.app.n8n.cloud/api/v1 (여기서 <name>은 여러분의 Cloud 서브도메인입니다).
- Self-hosted:
https://<your-instance-url>/api/v1.
사용 가능한 작업 및 파라미터에 대해서는 n8n node 문서를 참고하세요.
API 키 삭제#
- n8n에 로그인합니다.
- Settings > n8n API로 이동합니다.
- 삭제하려는 키 옆의 Delete를 선택합니다.
- Delete Forever를 선택하여 삭제를 확인합니다.
API 범위#
enterprise instances를 사용하는 사용자는 범위를 지정하여 API 키가 접근할 수 있는 리소스와 작업을 제한할 수 있습니다. 키의 용도에 맞게 필요한 최소한의 범위를 선택하세요.
Non-enterprise API 키는 계정의 모든 리소스와 기능에 완전히 접근할 수 있습니다.
Note
API 키 범위와 프로젝트 역할 범위 비교
API 키 범위는 인스턴스 수준에서 API 키가 수행할 수 있는 작업을 제어합니다. 이는 프로젝트 내에서 커스텀 역할을 정의하는 데 사용되는 프로젝트 역할 범위와는 다릅니다. 프로젝트 역할 범위에 대해서는 Custom project roles를 참고하세요.
다음 표는 범위가 지정된 API 키를 생성할 때 사용할 수 있는 범위를 리소스별로 그룹화하여 나열한 것입니다.
커뮤니티 패키지 범위#
| 범위 |
설명 |
communityPackage:install |
인스턴스에 커뮤니티 노드 패키지를 설치합니다. |
communityPackage:list |
설치된 커뮤니티 노드 패키지를 나열합니다. |
communityPackage:uninstall |
커뮤니티 노드 패키지를 제거합니다. |
communityPackage:update |
설치된 커뮤니티 노드 패키지를 업데이트합니다. |
자격 증명 범위#
| 범위 |
설명 |
credential:create |
자격 증명을 생성합니다. |
credential:read |
자격 증명과 그 데이터 스키마를 조회합니다. |
credential:list |
자격 증명을 나열합니다. |
credential:update |
자격 증명을 업데이트합니다. |
credential:delete |
자격 증명을 삭제합니다. |
credential:move |
자격 증명을 다른 프로젝트로 이전합니다. |
데이터 테이블 범위#
| 범위 |
설명 |
dataTable:create |
데이터 테이블을 생성합니다. |
dataTable:read |
데이터 테이블을 조회합니다. |
dataTable:list |
데이터 테이블을 나열합니다. |
dataTable:update |
데이터 테이블의 메타데이터를 업데이트합니다. |
dataTable:delete |
데이터 테이블을 삭제합니다. |
데이터 테이블 컬럼 범위#
| 범위 |
설명 |
dataTableColumn:create |
데이터 테이블에 칼럼을 추가합니다. |
dataTableColumn:read |
데이터 테이블 칼럼을 조회합니다. |
dataTableColumn:update |
데이터 테이블 칼럼을 업데이트합니다. |
dataTableColumn:delete |
데이터 테이블 칼럼을 삭제합니다. |
데이터 테이블 행 범위#
| 범위 |
설명 |
dataTableRow:create |
데이터 테이블에 행을 삽입합니다. |
dataTableRow:read |
데이터 테이블의 행을 읽어옵니다. |
dataTableRow:update |
데이터 테이블의 기존 행을 업데이트합니다. |
dataTableRow:delete |
데이터 테이블에서 행을 삭제합니다. |
dataTableRow:upsert |
필터 조건에 일치하는 행이 있으면 업데이트하고, 없으면 새 행을 삽입합니다. |
실행 범위#
| 범위 |
설명 |
execution:read |
실행 및 그 세부 정보를 조회합니다. |
execution:list |
실행 목록을 나열합니다. |
execution:retry |
실패한 실행을 재시도합니다. |
execution:stop |
실행 중인 실행을 중지합니다. |
execution:delete |
실행을 삭제합니다. |
실행 태그 범위#
| 범위 |
설명 |
executionTags:list |
실행에 할당된 주석 태그를 읽어옵니다. |
executionTags:update |
실행에 할당된 주석 태그를 업데이트합니다. |
폴더 범위#
| 범위 |
설명 |
folder:create |
프로젝트에 폴더를 생성합니다. |
folder:read |
폴더를 조회합니다. |
folder:list |
프로젝트의 폴더를 나열합니다. |
folder:update |
폴더를 업데이트합니다. |
folder:delete |
폴더를 삭제합니다. |
인사이트 범위#
| 범위 |
설명 |
insights:read |
실행 횟수, 실패율, 절약된 시간, 평균 실행 시간 등 인스턴스 인사이트 데이터를 읽어옵니다. |
프로젝트 범위#
| 범위 |
설명 |
project:create |
프로젝트를 생성합니다. |
project:list |
프로젝트를 나열합니다. |
project:update |
프로젝트를 업데이트합니다. |
project:delete |
프로젝트를 삭제합니다. |
보안 감사 범위#
| 범위 |
설명 |
securityAudit:generate |
인스턴스에 대한 보안 감사 보고서를 생성합니다. |
소스 컨트롤 범위#
| 범위 |
설명 |
sourceControl:pull |
연결된 소스 컨트롤 리포지터리에서 인스턴스로 변경 사항을 가져옵니다(pull). |
태그 범위#
| 범위 |
설명 |
tag:create |
전역 태그 레지스트리에 태그를 생성합니다. |
tag:read |
태그를 조회합니다. |
tag:list |
태그를 나열합니다. |
tag:update |
태그를 업데이트합니다. |
tag:delete |
태그를 삭제합니다. |
사용자 범위#
| 범위 |
설명 |
user:create |
인스턴스에 사용자를 초대하거나 생성합니다. |
user:read |
사용자를 조회합니다. |
user:list |
사용자를 나열합니다. |
user:changeRole |
사용자의 전역(인스턴스 수준) 역할을 변경합니다. |
user:enforceMfa |
예약된 범위입니다. 이 범위를 소비하는 /api/v1/ 엔드포인트가 없으므로, Public API 키에서 이 범위를 선택해도 공개적으로 미치는 영향은 없습니다. |
user:delete |
인스턴스에서 사용자를 삭제합니다. |
변수 범위#
| 범위 |
설명 |
variable:create |
인스턴스 변수를 생성합니다. |
variable:list |
인스턴스 변수를 나열합니다. |
variable:update |
인스턴스 변수를 업데이트합니다. |
variable:delete |
인스턴스 변수를 삭제합니다. |
워크플로 범위#
| 범위 |
설명 |
workflow:create |
워크플로를 생성합니다. |
workflow:read |
워크플로와 그 세부 정보를 조회합니다. |
workflow:list |
워크플로를 나열합니다. |
workflow:update |
워크플로를 업데이트합니다. |
workflow:delete |
워크플로를 삭제, 보관(archive), 또는 보관 해제(unarchive)합니다. |
workflow:move |
워크플로를 다른 프로젝트로 이전합니다. |
workflow:activate |
워크플로를 활성화 또는 비활성화합니다. Public API에서는 "publish/unpublish"(/workflows/{id}/activate 및 /workflows/{id}/deactivate)라고도 합니다. |
워크플로 태그 범위#
| 범위 |
설명 |
workflowTags:list |
워크플로에 할당된 태그를 읽어옵니다. |
workflowTags:update |
워크플로에 할당된 태그를 업데이트합니다. |
