n8n API Guide: REST API Calls, Authentication & Credential Management

Overview

In this tutorial, you will learn how to collaborate effectively within your n8n workspace by managing user roles and sharing workflows securely. You will also discover how to safely share credentials without exposing sensitive data and how to programmatically control your n8n instance using the n8n API. These enterprise-grade features will help you scale automation projects efficiently while maintaining security and control.

For more advanced workflow structuring, consider exploring Sub-workflows in n8n to modularize your automation projects.

Understanding User Roles and Access Management in n8n

Effective collaboration in n8n starts with managing user access through defined roles. n8n supports three primary user roles:

• Owner: Has full access to everything in the workspace, including managing users, workflows, and credentials. Only one owner is allowed per instance.
• Admin: Can manage other users, workflows, and credentials but cannot modify the owner role.
• Member: Standard users who can create and manage their own workflows but do not have global control.

Why Role-Based Access Matters

• Security: Restrict access to sensitive API keys and credentials only to those who need them.
• Prevent Errors: Limit who can modify critical workflows to avoid accidental disruptions.
• Controlled Collaboration: Allow team members to execute or edit workflows relevant to their responsibilities without exposing everything.

How to Manage Users in n8n

1. Click your username in the top right corner of your n8n workspace.
2. Select Settings from the dropdown.
3. Navigate to the Users tab on the left panel.
4. Here, you can see existing users and their roles.
5. To add a new user, click the Invite button.
6. Enter the email address and assign a role (Member or Admin, depending on your plan).
7. The invited user will receive an email and must accept the invitation to join your workspace.

Note: On the basic or starter plan, you can only have one admin and one owner. To add more admins, upgrade to the Pro or higher plan.

Sharing Workflows for Team Collaboration

By default, workflows in n8n are private and accessible only to their creators. To collaborate, workflows need to be explicitly shared with other users.

Steps to Share a Workflow

1. Open the workflow you want to share.
2. Click the Share button at the top.
3. In the popup, select the users you want to share the workflow with.
4. Assign the role of Editor to allow them to modify the workflow.
5. Click Save to apply the sharing permissions.

You can remove access by clicking the delete icon next to a user and saving the changes.

Best Practices for Workflow Sharing

• Share workflows only with users who need access.
• Use the Editor role for collaborators who need to modify the workflow.
• Regularly review shared workflows to maintain security and relevance.

Sharing workflows effectively is especially important when building AI-powered automations. For example, check out the AI Automation with n8n and OpenAI lesson to see how collaboration can enhance AI workflow development.

Secure Credential Management and Sharing

Sharing workflows alone is not enough—credentials used in these workflows (such as API keys) must also be shared securely to enable execution without exposing sensitive information.

How Credential Sharing Works in n8n

• Credentials can be shared with other users or entire projects.
• Shared credentials are usable in workflows by those users but the actual secret values (API keys, tokens) are never exposed.
• Only owners and admins can revoke credential access.
• Users without access to a credential cannot execute workflows that depend on it.

Steps to Share Credentials

1. Go to your n8n workspace and click your username.
2. Select Personal Workspace.
3. Click the Credentials tab.
4. Select the credential you want to share.
5. In the Sharing section, choose the users or project to share with.
6. Click Save to confirm.

Revoking Credential Access

• Open the credential as above.
• Remove users from the sharing list.
• Save the changes to revoke access.

For detailed information on credential management, refer to the n8n User Management Documentation{:target="_blank"}.

Programmatic Control of n8n via API

n8n provides a comprehensive REST API to programmatically manage your workflows, users, credentials, and executions. This allows you to automate workspace management and even control workflow activation schedules.

Use Cases for API Control

• Automatically activate or deactivate workflows during business hours.
• Fetch execution logs for monitoring and debugging.
• Create, update, or delete workflows and credentials programmatically.
• Manage users and permissions dynamically.

Creating an API Key for n8n API Access

1. Click your username and open Settings.
2. Navigate to the n8n API tab.
3. Click Create API Key.
4. Enter a name for the key (e.g., internal-api-key).
5. Set an expiration date (recommended for security).
6. Select scopes (permissions) for the API key (Pro plan required for granular scopes).
7. Click Save and copy the generated API key.

Security Tip: Always set an expiration for API keys and rotate them periodically.

Making API Calls Using the HTTP Request Node

You can call the n8n API within workflows using the HTTP Request node. Here's how to fetch the list of users:

1. Create a new workflow with a Manual Trigger node.

2. Add an HTTP Request node.

3. Set the method to GET.

4. Set the URL to your n8n instance API endpoint for users:

   https://your-n8n-instance.com/api/v1/users
   

5. Configure authentication:

   • Select Generic Credential Type.
   • Use header authentication with the header name x-n8n-api-key.
   • Create a new credential with the API key you generated.

6. Add the header Accept: application/json in Send Headers.

7. Execute the node to fetch all users.

Example HTTP Request Node Configuration

{
  "method": "GET",
  "url": "https://your-n8n-instance.com/api/v1/users",
  "authentication": "genericCredentialType",
  "genericCredentialType": "headerAuth",
  "headers": [
    { "name": "x-n8n-api-key", "value": "YOUR_API_KEY" },
    { "name": "Accept", "value": "application/json" }
  ]
}

Fetching Active Workflows with Query Parameters

To fetch only active workflows, add query parameters:

• Key: active
• Value: true

The URL endpoint is:

https://your-n8n-instance.com/api/v1/workflows

For more details on the API endpoints and usage, consult the n8n API Reference{:target="_blank"} and the official n8n documentation{:target="_blank"}.

Using the Built-In n8n API Node

For easier integration within n8n workflows, you can use the dedicated n8n API node, which wraps many API actions without manually configuring HTTP requests.

How to Use the n8n API Node

1. Add the n8n API node to your workflow.
2. Select the desired action, such as Get Many Executions.
3. Configure the API credentials (API key and base URL).
4. Set parameters (e.g., limit results).
5. Execute the node to retrieve data.

This node is useful for automating workspace management entirely within n8n, without external code. It can be combined with AI-powered content generation workflows like the AI Blog Writer with n8n to create powerful automation pipelines.

Common Mistakes and Troubleshooting

User and Role Management

• Mistake: Trying to add multiple owners or admins on a basic plan.
  • Fix: Upgrade to Pro plan to unlock multiple admin roles.
• Mistake: Inviting users but not confirming their acceptance.
  • Fix: Ensure users accept the invitation email to join the workspace.

Workflow Sharing

• Mistake: Sharing workflows but forgetting to share credentials.
  • Fix: Always share necessary credentials alongside workflows to enable execution.
• Mistake: Not clicking Save after sharing workflows or credentials.
  • Fix: Changes are only applied after saving.

API Usage

• Mistake: Using an expired or invalid API key.
  • Fix: Generate a new API key and update credentials.
• Mistake: Not including required headers (x-n8n-api-key, Accept) in API calls.
  • Fix: Always include these headers for authentication and response format.
• Mistake: Forgetting to append /api/v1/ to the API endpoint URL.
  • Fix: Ensure the URL is correctly formatted as https://your-instance.com/api/v1/endpoint.

Quick Reference Cheat Sheet

Additional Resources

• n8n User Management Documentation{:target="_blank"}
• n8n API Reference{:target="_blank"}

By mastering these collaboration, credential sharing, and API control techniques, you will be well-equipped to build and scale secure, efficient automation workflows with your team in n8n.