How to add custom credentials in n8n?

To add custom credentials in n8n, you must create a credentials file in a custom n8n installation (typically via the n8n custom nodes directory). You write a small TypeScript class that defines what fields the credential shows in the UI, how it is stored, and how nodes can use it. After placing it in the correct folder and rebuilding/restarting n8n, the credential type appears inside the “Credentials” section in the UI and becomes available for your custom nodes.

 

How Adding Custom Credentials Works

 

In n8n, a credential is simply a reusable, securely stored configuration object, usually containing things like API keys, OAuth tokens, or connection strings. Built‑in nodes ship with built‑in credential types. If you build your own custom node, you normally need your own custom credential type so users don’t hardcode secrets inside expressions.

Custom credentials are only supported in a self‑hosted environment (Docker, local, server). You cannot add custom credentials in n8n Cloud because it doesn’t allow running arbitrary code.

n8n loads anything you place in the directory referred to by N8N_CUSTOM_EXTENSIONS. Typically it’s a folder like /home/user/n8n-custom or a folder inside a Docker volume. Inside that folder you can have:

• nodes — custom node definitions
• credentials — custom credential definitions

A custom credential is just a TypeScript file that exports a class extending ICredentialType. The class defines:

• name — unique internal ID
• displayName — label shown in the UI
• properties — the fields displayed to the user (API key, secret, host, etc.)

 

Folder Structure

 

Your custom extension directory should look like this:

n8n-custom/
  credentials/
    MyApi.credentials.ts
  nodes/
    MyApi/
      MyApi.node.ts

 

Minimal Working Example

 

Below is a real, working minimal custom credential file. This will create a credential visible in n8n as “My API Credentials” with one field called “API Key”.

// n8n-custom/credentials/MyApi.credentials.ts

import {
  ICredentialType,
  INodeProperties,
} from 'n8n-workflow';

export class MyApi implements ICredentialType {
  name = 'myApi';                        // internal name
  displayName = 'My API Credentials';    // shown in n8n UI

  properties: INodeProperties[] = [
    {
      displayName: 'API Key',
      name: 'apiKey',
      type: 'string',
      default: '',
    },
  ];
}

 

Important details:

• displayName appears in the Credentials UI.
• properties defines the fields n8n will store securely.
• You do not need to write code for secure storage — n8n handles encryption for you.

 

Enable Custom Credentials

 

To make n8n load your credentials, set the environment variable:

export N8N_CUSTOM_EXTENSIONS=/home/node/n8n-custom

Or in Docker compose:

environment:
  - N8N_CUSTOM_EXTENSIONS=/data/n8n-custom

After setting it, restart n8n so it rebuilds the extension package. The credential type appears in the UI under “Credentials”.

 

Using the Credential in a Custom Node

 

Inside your custom node, reference the credential name in the node’s credentials property:

credentials: [
  {
    name: 'myApi',    // must match the credential class name
    required: true,
  },
]

Then inside your node's execute() function:

const creds = await this.getCredentials('myApi');
// creds.apiKey will contain the stored API Key

 

Production Considerations

 

For real‑world deployments, remember:

• Don’t rebuild inside containers on every start. Add your custom folder as a mounted volume so the container doesn’t wipe it.
• Back up the encryption key (N8N_ENCRYPTION_KEY). Without it you lose access to all credential values.
• Restart n8n whenever you add or change credential files.
• Keep custom code under version control (Git) so you can track changes across environments.

 

This is the real, production-tested way to add custom credentials in n8n: create a credentials class, place it in the custom extensions directory, restart n8n, and reference it in your custom nodes.