Skip to main content
The key must belong to an instance owner or admin. The Admin role is available on n8n Cloud Pro and Enterprise and on self-hosted Enterprise; on other plans the owner creates the key. n8n says “The n8n API isn’t available during the free trial.”

Find your Instance URL

The Instance URL is the web address of your n8n instance: the host name, plus the port and base path if your address includes them.

  • Open n8n in your browser and copy the address from the address bar.
  • Delete everything after the host name, port and base path, such as /home/workflows or /projects/abc123/workflows.
  • Format on n8n Cloud: https://{subdomain}.app.n8n.cloud
  • Format when self-hosted: https://{host}, with :{port} and /{base path} if your address includes them
  • Example: https://acme.app.n8n.cloud
  • Example with a base path: https://example.com/n8n
  • Your n8n instance must be reachable from the internet over HTTPS, without a sign-in page in front of it. A self-hosted instance that only accepts plain HTTP cannot connect.
  • Paste it into the Instance URL field in StackOne Hub.

Create the API key

An n8n API key can only use the scopes you grant it, and only those that the role of the user who creates it allows.

1

Sign in to n8n

Sign in to your n8n instance as an owner or, where your plan has the role, an admin.

  • Enter your Email and Password, then select Sign in.
  • A key can only hold the scopes that the signed-in user’s role allows, so sign in as an owner or admin rather than as a member.
n8n sign-in page with the Email and Password fields
2

Open Settings

Select Settings at the bottom of the left sidebar.

n8n Overview page with Settings highlighted at the bottom of the sidebar
3

Open the n8n API settings

In the Settings menu, select n8n API.

  • You can also open your Instance URL with /settings/api added, for example https://acme.app.n8n.cloud/settings/api.
Settings menu with n8n API highlighted
4

Create the key

On the API page, select Create API key.

n8n API page with the Create API key button highlighted
5

Name the key

In the Create API Key dialog, fill in the key details.

  • Label: StackOne Integration
  • Choose an Expiration: 7 days, 30 days (the default), 60 days, 90 days, Custom or Never. When the key expires, the connection stops working until you paste a new key into StackOne Hub.
Create API Key dialog with the Label, Expiration and Scopes fields and the Save button
6

Choose the scopes

Enables actions: Add Project Members, Add Project To Promotion Connection, Apply Project Workflows, Apply Promotion Package, Archive Workflow, Cancel Test Run, Clear Data Table Rows, Clone Promotion Checkout, Continue Apply Project Workflows, Continue Apply Promotion Package, Create Credential, Create Credential Type Policy Document, Create Data Table, Create Data Table Column, Create Data Table Rows, Create Folder, Create Log Streaming Destination, Create Node Type Policy Document, Create Project, Create Promotion Connection, Create Promotion Provider, Create Role, Create Role Mapping Rule, Create Tag, Create Test Run, Create User, Create Variable, Create Workflow, Delete Credential, Delete Credential Type Policy Document, Delete Data Table, Delete Data Table Column, Delete Data Table Rows, Delete Execution, Delete Folder, Delete Log Streaming Destination, Delete Node Type Policy Document, Delete Project, Delete Promotion Config, Delete Promotion Connection, Delete Promotion Provider, Delete Role, Delete Role Mapping Rule, Delete Tag, Delete User, Delete Variable, Delete Workflow, Disconnect Promotion Checkout, Export N8n Package, Generate Security Audit, Get Credential, Get Credential Type Instance Policy, Get Credential Type Policy Attachments, Get Credential Type Policy Document, Get Credential Type Project Policy, Get Data Table, Get Execution, Get Folder, Get Insights Summary, Get LDAP Configuration, Get Log Streaming Destination, Get Node Type Instance Policy, Get Node Type Policy Attachments, Get Node Type Policy Document, Get Node Type Project Policy, Get OIDC Configuration, Get Otel Settings, Get Promotion Connection, Get Promotion Provider, Get Role, Get SAML Configuration, Get Security Policy, Get Source Control Status, Get Tag, Get Test Run, Get Unified Group, Get Unified Role, Get Unified User, Get User, Get Workflow, Get Workflow Version, Import N8n Package, Import N8n Package Selection, Install Community Package, List Community Packages, List Credential Type Policy Documents, List Credentials, List Data Table Columns, List Data Table Rows, List Data Tables, List Execution Tags, List Executions, List Folders, List LDAP Sync History, List Log Streaming Destinations, List Log Streaming Event Types, List Node Type Policy Documents, List Project Members, List Projects, List Promotion Changes, List Promotion Connection Projects, List Promotion Connections, List Promotion Provider Repositories, List Promotion Providers, List Promotion Repository Branches, List Role Mapping Rules, List Roles, List Tags, List Test Run Cases, List Test Runs, List Unified Groups, List Unified Roles, List Unified Users, List Users, List Variables, List Workflow Tags, List Workflow Versions, List Workflows, Move Role Mapping Rule, Promote All Projects, Promote Project Workflows, Publish Workflow, Pull Source Control, Push Source Control, Remove Project From Promotion Connection, Remove Project Member, Replace Credential Type Instance Policy, Replace Credential Type Policy Attachments, Replace Credential Type Project Policy, Replace Node Type Instance Policy, Replace Node Type Policy Attachments, Replace Node Type Project Policy, Retry Execution, Run LDAP Sync, Stop Execution, Stop Many Executions, Test Credential, Test Log Streaming Destination, Test Otel Trace, Transfer Credential, Transfer Workflow, Unarchive Workflow, Uninstall Community Package, Unpublish Workflow, Update Community Package, Update Credential, Update Credential Type Policy Document, Update Data Table, Update Data Table Column, Update Data Table Rows, Update Execution Tags, Update Folder, Update LDAP Configuration, Update Log Streaming Destination, Update Node Type Policy Document, Update OIDC Configuration, Update Otel Settings, Update Project, Update Project Member Role, Update Promotion Connection, Update Promotion Provider, Update Role, Update Role Mapping Rule, Update SAML Configuration, Update Security Policy, Update Tag, Update User Role, Update Variable, Update Workflow, Update Workflow Tags, Upsert Data Table Row, Upsert Promotion Apply Config, Upsert Promotion Promote Config

Under Scopes, keep All to let StackOne use every action. To limit the key, select Custom and enable only the scopes for the actions you plan to use. The count below the options shows how many scopes your role allows: a member sees 61, while an owner or admin sees more.

7

Check what each scope covers

n8n groups the Custom scopes by resource. The notes below explain the most important scopes and where to find each group.

  • user:list and user:read read the users, their global roles and the members of each team project.
  • project:list reads team projects. Without it, project roles and groups cannot be read, and requests that expand them fail.
  • role:list and role:read read the role definitions. They are available on n8n 2.36.0 or later, where the connection test reads the role list and rejects a key without role:list.
  • Workflow and executions covers workflows, versions, publishing, workflow tags, executions, retries and execution tags.
  • Credentials and variables covers credentials and variables.
  • Data tables covers data tables, their columns and rows.
  • Projects covers team projects and their members.
  • Folders, tags covers folders and tags.
  • Members covers users.
  • Instance operations covers source control, community packages, the security audit, insights, and credential and node type policies.
  • Event Bus Destination covers log streaming destinations, which webhook events require.
  • Agent covers agent export.
  • Test Run covers test runs.
  • A member key only lists the scopes that its role allows, so the role, roleMappingRule and gitConnection scopes and the destination create and delete scopes do not appear. On an owner or admin key, find them with the scope search box.
  • Read only grants read access to workflows and data only, so any action that creates, changes or deletes something is rejected.
  • On n8n releases earlier than 2.14.0, only Enterprise plans show Scopes, and keys on other plans have full access.
8

Copy the key

Select Save, then copy the key that n8n displays and store it securely for later use.

  • The key is shown only once and cannot be retrieved later. n8n says “Make sure to copy your API key now as you will not be able to see this again.”
  • Paste it into the API Key field in StackOne Hub.

Understand role and plan limits

On n8n 2.36.0 or later, a key created by a member is rejected when you connect, because n8n only allows owners and admins to read roles and projects. The error message states that an owner or admin key is required.

  • On a licence without projects, users still load with their global roles, but their project roles and groups are empty, and listing groups is rejected with n8n’s licence message.
  • On a licence with a user limit, n8n rejects the users list with its own message.
  • Variables, LDAP, SAML, OIDC, log streaming, source control and environments are paid n8n features. On a plan without them, those actions are rejected even when the key has every scope.

Revoke the key

To stop StackOne from accessing your n8n instance, revoke the key.

  • Navigate to Settings > n8n API.
  • Open the actions menu on the key’s row and select Revoke.
  • Confirm with Revoke.
  • On n8n releases earlier than 2.26.0, select Delete next to the key and confirm with Delete Forever.
1

Connect

  • Click Connect.
  • If applicable, the provider will redirect you to a sign-in or authorization page. Complete the provider’s authorization flow.
  • Once authorization is successful, you will see a confirmation popup.
2

Use Actions

Connect an AI platform to the linked account’s actions. See AI Platforms.Other ways to call actions are listed in Protocols & SDKs.

Next Steps

Webhooks setup

Configure receiving Events for n8n into StackOne.