n8n

Custom Ocean integration

This integration was created using the custom Ocean integration framework.
Please note that:

1. This integration will not be listed in the Connectors page of your Port application, and must be installed manually using the instructions on this page.
2. This integration will not create components (e.g. blueprints, mapping, etc.) in your portal automatically, you will need to create them manually using the instructions on this page.

Port's n8n integration ingests n8n resources into your software catalog using the No-code Ocean custom integration framework. It focuses on three key data sources: users, projects, and workflows.

Supported resources

The n8n integration can ingest the following resources into Port:

• n8nUser – n8n users from /v1/users.
• n8nProject – n8n projects from /v1/projects.
• n8nWorkflow – n8n workflows from /v1/workflows.

These resources provide visibility into your n8n automation platform, including user management, project organization, and workflow definitions.

Prerequisites

To use this integration, you need:

1. Port credentials (CLIENT_ID and CLIENT_SECRET)
2. n8n instance URL (e.g., https://your-instance.com/api)
3. n8n API key (see n8n API docs)

To create an n8n API key:

1. Navigate to your n8n instance and sign in to your account.
2. Go to Settings → API.
3. Click Create API Key.
4. Give your key a name (e.g., "Port Integration") and copy the API key.
5. Store the API key securely.

API key security

Store your API key securely and never share it. The key provides access to your n8n instance data.

Review the n8n API reference to understand the exact response structure returned by each endpoint.

Installation

The no-code Ocean custom integration can be installed in two ways:

• Hosted by Port — Port manages the infrastructure; configure the connection in the Port UI.
• Self-hosted — Run the integration in your own infrastructure using Helm or Docker.

Choose one of the following options:

Hosted by Port

Set up in Port

1. Go to the custom connector page and open the no-code Ocean custom integration form.
2. Configure:
   • Identifier: n8n-integration.
   • Base URL: your n8n instance API URL (for example https://your-instance.com/api).
   • Authentication type: api_key.
   • API key header: X-N8N-API-KEY.
   • API key: your n8n API key.
3. Expand Advanced configuration and set:
   • Pagination type: cursor.
   • Pagination parameter: cursor.
   • Page size parameter: limit.
   • Page size: 100.
   • Cursor path: nextCursor.
   • Has more path: nextCursor.
4. Click Save & install.

Continue with the mappings

After the integration is installed, continue to the Configuration section on this page and add the resource mappings.

Helm

Prerequisites

• A Kubernetes cluster - the integration's container chart will be deployed to this cluster.

• kubectl and helm must be installed on your machine. Your kubectl CLI must be connected to the Kubernetes cluster where you plan to install the integration.

Installation

Add Port's Helm repo and install the no-code Ocean custom integration:

Replace placeholders

Remember to replace the placeholders for YOUR_PORT_CLIENT_ID, YOUR_PORT_CLIENT_SECRET, YOUR_N8N_INSTANCE_URL, and YOUR_N8N_API_KEY.

helm repo add port-labs https://port-labs.github.io/helm-charts
helm repo update

helm install n8n-integration port-labs/port-ocean \
--set initializePortResources=true \
--set scheduledResyncInterval=120 \
--set sendRawDataExamples=true \
--set integration.type="custom" \
--set integration.eventListener.type="POLLING" \
--set integration.identifier=n8n-integration \
--set integration.config.baseUrl=https://your-instance.com/api \
--set integration.config.authType=api_key \
--set integration.config.apiKeyHeader=X-N8N-API-KEY \
--set integration.secrets.apiKey=YOUR_N8N_API_KEY \
--set integration.config.paginationType=cursor \
--set integration.config.paginationParam=cursor \
--set integration.config.sizeParam=limit \
--set integration.config.pageSize=100 \
--set integration.config.cursorPath=nextCursor \
--set integration.config.hasMorePath=nextCursor \
--set port.clientId=YOUR_PORT_CLIENT_ID \
--set port.clientSecret=YOUR_PORT_CLIENT_SECRET \
--set port.baseUrl="https://api.port.io"

Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

Configuration parameters

Parameter	Description	Example	Required
port.clientId	Your Port client id.		✅
port.clientSecret	Your Port client secret.		✅
port.baseUrl	Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US).		✅
integration.config.baseUrl	Base URL for your n8n instance API.	https://your-instance.com/api	✅
integration.config.authType	Authentication type for n8n (use api_key for n8n).	api_key	✅
integration.config.apiKeyHeader	Header name for the API key.	X-N8N-API-KEY	✅
integration.secrets.apiKey	n8n API key.		✅
integration.config.paginationType	Pagination type used by n8n API.	cursor	✅
integration.config.paginationParam	Query parameter name for pagination cursor.	cursor	✅
integration.config.sizeParam	Query parameter name for page size.	limit	✅
integration.config.pageSize	Number of items per page.	100	✅
integration.config.cursorPath	JSON path to cursor value in response.	nextCursor	✅
integration.config.hasMorePath	JSON path to check if more pages exist.	nextCursor	✅
integration.eventListener.type	The event listener type. Read more about event listeners	POLLING	✅
integration.type	The integration type (must be custom for the no-code Ocean custom integration)..	custom	✅
integration.identifier	Unique identifier for this integration instance.	n8n-integration	✅
initializePortResources	Create default blueprints and mappings on first run.	true	❌
sendRawDataExamples	Send sample payloads for easier mapping.	true	❌

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, see Ocean advanced configuration.

Docker

To run the integration using Docker for a one-time sync:

Replace placeholders

Remember to replace the placeholders for YOUR_PORT_CLIENT_ID, YOUR_PORT_CLIENT_SECRET, YOUR_N8N_INSTANCE_URL, and YOUR_N8N_API_KEY.

docker run -i --rm --platform=linux/amd64 \
  -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \
  -e OCEAN__INITIALIZE_PORT_RESOURCES=true \
  -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \
  -e OCEAN__INTEGRATION__IDENTIFIER=n8n-integration \
  -e OCEAN__INTEGRATION__CONFIG__BASE_URL="https://your-instance.com/api" \
  -e OCEAN__INTEGRATION__CONFIG__AUTH_TYPE="api_key" \
  -e OCEAN__INTEGRATION__CONFIG__API_KEY_HEADER="X-N8N-API-KEY" \
  -e OCEAN__INTEGRATION__CONFIG__API_KEY="YOUR_N8N_API_KEY" \
  -e OCEAN__INTEGRATION__CONFIG__PAGINATION_TYPE="cursor" \
  -e OCEAN__INTEGRATION__CONFIG__PAGINATION_PARAM="cursor" \
  -e OCEAN__INTEGRATION__CONFIG__SIZE_PARAM="limit" \
  -e OCEAN__INTEGRATION__CONFIG__PAGE_SIZE="100" \
  -e OCEAN__INTEGRATION__CONFIG__CURSOR_PATH="nextCursor" \
  -e OCEAN__INTEGRATION__CONFIG__HAS_MORE_PATH="nextCursor" \
  -e OCEAN__PORT__CLIENT_ID="YOUR_PORT_CLIENT_ID" \
  -e OCEAN__PORT__CLIENT_SECRET="YOUR_PORT_CLIENT_SECRET" \
  -e OCEAN__PORT__BASE_URL="https://api.port.io" \
  ghcr.io/port-labs/port-ocean-custom:latest

Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, see Ocean advanced configuration.

Set up data model

Before syncing data, create the blueprints that define your n8n entities (users, projects, and workflows).

To create the blueprints:

1. Go to the Data model page in Port.

2. Click the + Blueprint button.

3. Copy each blueprint JSON from the sections below.

   n8n User blueprint (click to expand)

   {
     "identifier": "n8nUser",
     "description": "This blueprint represents an n8n user",
     "title": "n8n User",
     "icon": "User",
     "schema": {
       "properties": {
         "created_at": {
           "type": "string",
           "title": "Created At",
           "format": "date-time"
         },
         "is_active": {
           "type": "boolean",
           "title": "Is Active"
         },
         "email": {
           "type": "string",
           "title": "Email"
         },
         "full_name": {
           "type": "string",
           "title": "Full Name"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {}
   }

   n8n Project blueprint (click to expand)

   {
     "identifier": "n8nProject",
     "description": "This blueprint represents an n8n project",
     "title": "n8n Project",
     "icon": "OpenFolder",
     "schema": {
       "properties": {},
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {}
   }

   n8n Workflow blueprint (click to expand)

   {
     "identifier": "n8nWorkflow",
     "description": "This blueprint represents an n8n workflow",
     "title": "n8n Workflow",
     "icon": "Pipeline",
     "schema": {
       "properties": {
         "created_at": {
           "type": "string",
           "title": "Created At",
           "format": "date-time"
         },
         "updated_at": {
           "type": "string",
           "title": "Updated At",
           "format": "date-time"
         },
         "is_active": {
           "type": "boolean",
           "title": "Is Active"
         },
         "is_archived": {
           "type": "boolean",
           "title": "Is Archived"
         },
         "nodes": {
           "items": {
             "type": "object"
           },
           "icon": "DefaultProperty",
           "type": "array",
           "title": "Nodes"
         },
         "connections": {
           "type": "object",
           "title": "Connections"
         },
         "trigger_count": {
           "type": "number",
           "title": "Trigger Count"
         },
         "tags": {
           "items": {
             "type": "string"
           },
           "type": "array",
           "title": "Tags"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {
       "project": {
         "title": "Project",
         "target": "n8nProject",
         "required": false,
         "many": false
       }
     }
   }

4. Click Save after each blueprint is added.

Configuration

Each resource maps an n8n endpoint to the Port entities defined above.

Key mapping components:

• kind – API endpoint path appended to your n8n base URL.
• selector – Request payload, pagination controls, and data selection logic.
• port.entity.mappings – JQ expressions that transform the API payload into Port entities.

To configure the mapping:

1. Go to the connectors page of your portal.

2. Find your n8n integration in the list.

3. Click on the integration to open the mapping editor.

4. Add the resource mapping configurations below.

   Complete n8n mapping configuration (click to expand)

   deleteDependentEntities: true
   createMissingRelatedEntities: true
   enableMergeEntity: true
   resources:
     - kind: /v1/users
       selector:
         query: 'true'
         data_path: .data
       port:
         entity:
           mappings:
             identifier: .id
             title: .email
             blueprint: '"n8nUser"'
             properties:
               full_name: >-
                 if (.firstName // null) != null or (.lastName // null) != null
                 then ((.firstName // "") + " " + (.lastName // "")) else .email
                 end
               is_active: (.isPending | not)
               created_at: .createdAt
               email: .email
     - kind: /v1/projects
       selector:
         query: 'true'
         data_path: .data
       port:
         entity:
           mappings:
             identifier: .id
             title: .name
             blueprint: '"n8nProject"'
             properties: {}
     - kind: /v1/workflows
       selector:
         query: 'true'
         data_path: .data
       port:
         entity:
           mappings:
             identifier: .id
             title: .name
             blueprint: '"n8nWorkflow"'
             properties:
               nodes: .nodes
               connections: .connections
               trigger_count: .triggerCount
               is_active: .active
               is_archived: .isArchived
               tags: (.tags | map(.name))
               created_at: .createdAt
               updated_at: .updatedAt
             relations:
               project: .shared[0].projectId

5. Click Save to save the mapping.

Customization

If you want to expand beyond the starter resources, use the interactive builder to:

1. Test additional n8n endpoints.
2. Explore the response shape and detected property types.
3. Generate blueprint JSON and mapping snippets automatically.
4. Export installation commands with your configuration pre-filled.

Start with the users, projects, and workflows entities above, then add more resources (such as executions or credentials) once you verify the value.

API Reference

• n8n Projects API
• n8n Users API
• n8n Workflows API