# How to Add Custom Credentials in n8n

- Tool: n8n
- Difficulty: Beginner
- Time required: 10-15 minutes
- Compatibility: n8n 1.0+ (self-hosted and Cloud)
- Last updated: March 2026

## TL;DR

To add custom credentials in n8n, go to the Credentials section in the left sidebar, click Add Credential, and choose the service type or create a custom API credential using the Header Auth or Generic Credential type. Enter your API key, token, or username and password, then save. n8n encrypts all credential data using N8N_ENCRYPTION_KEY, and you can reference the credential from any node that supports it.

## Creating and Managing Custom API Credentials in n8n

Every external service you connect to from n8n requires authentication credentials. n8n provides built-in credential types for hundreds of services like Slack, Google Sheets, and OpenAI. For services without a built-in type, you can create custom credentials using Generic Credential types such as Header Auth, Query Auth, or OAuth2. This tutorial shows you how to create, test, and manage credentials for both built-in and custom services.

## Before you start

- A running n8n instance (self-hosted or Cloud)
- An API key or token from the service you want to connect
- Access to the n8n editor in a browser

## Step-by-step guide

### 1. Open the Credentials panel and create a new credential

In the n8n editor, click on the Credentials icon in the left sidebar (it looks like a key). This opens the Credentials panel showing all your saved credentials. Click the Add Credential button in the top-right corner. A search dialog appears where you can type the name of the service you want to connect. If n8n has a built-in credential type for that service, it will appear in the search results. Select it to open the credential configuration form with fields specific to that service.

**Expected result:** The credential creation form opens with fields specific to the selected service type.

### 2. Fill in the credential fields for a built-in service

Each built-in credential type has specific fields. For example, OpenAI credentials require an API Key field. Slack credentials require an OAuth setup with Client ID, Client Secret, and redirect URL. Google services require OAuth2 credentials from the Google Cloud Console. Fill in all required fields using the values from your service's dashboard. Some credential types have a Test button that lets you verify the credentials work before saving. Always test when available to catch typos or expired keys early.

**Expected result:** All required fields are filled in. If a Test button is available, clicking it shows a success message confirming the credentials are valid.

### 3. Create a custom Header Auth credential for an unsupported API

If the API you want to connect does not have a built-in credential type in n8n, use the Header Auth credential. Search for Header Auth in the Add Credential dialog and select it. This lets you define a custom HTTP header that n8n will include in every request made by nodes using this credential. Enter the header name (such as X-API-Key, Authorization, or any custom header the API expects) and the header value (your API key or token). Name the credential descriptively so you can identify it later.

**Expected result:** A Header Auth credential is saved with your custom header name and value, ready to be used with HTTP Request nodes.

### 4. Use a custom credential with the HTTP Request node

The HTTP Request node is the universal way to call any API in n8n. Open or add an HTTP Request node, then under Authentication, select the type that matches your credential (Predefined Credential Type for built-in types, or Generic Credential Type for Header Auth, Query Auth, or OAuth2). Select the credential you just created from the dropdown. Now any request made by this node will automatically include the authentication header or parameters you configured. You do not need to manually add auth headers in the Header Parameters section.

**Expected result:** The HTTP Request node is configured with your credential and automatically includes authentication in every request.

### 5. Understand credential encryption and the encryption key

n8n encrypts all credential data at rest using the N8N_ENCRYPTION_KEY environment variable. This key is generated automatically on first run and stored in the .n8n directory. If you lose this key, all saved credentials become unrecoverable — you will need to re-enter every credential. For self-hosted installations, always back up the encryption key separately from the database. Set it explicitly in your environment variables or docker-compose.yml so it survives container recreations.

```
# Set in docker-compose.yml to ensure persistence
environment:
  - N8N_ENCRYPTION_KEY=your-secure-random-string-here

# Or in .env file
N8N_ENCRYPTION_KEY=your-secure-random-string-here

# Generate a secure random key
openssl rand -hex 32
```

**Expected result:** Your encryption key is explicitly set and backed up, ensuring credentials survive container or server changes.

## Complete code example

File: `code-node-credential-test.js`

```javascript
// Code node: Test API credentials by making a request
// This is useful when the built-in Test button is not available
// Place this Code node after an HTTP Request node to validate the response

const items = $input.all();
const results = [];

for (const item of items) {
  const statusCode = item.json.statusCode || item.json.$response?.statusCode;
  const body = item.json;

  if (statusCode === 401 || statusCode === 403) {
    results.push({
      json: {
        credentialStatus: 'INVALID',
        error: 'Authentication failed. Check your API key or token.',
        statusCode: statusCode,
        suggestion: 'Verify the credential in n8n Settings → Credentials'
      }
    });
  } else if (statusCode >= 200 && statusCode < 300) {
    results.push({
      json: {
        credentialStatus: 'VALID',
        message: 'Credentials are working correctly',
        statusCode: statusCode
      }
    });
  } else {
    results.push({
      json: {
        credentialStatus: 'UNKNOWN',
        message: 'Unexpected response code',
        statusCode: statusCode,
        body: body
      }
    });
  }
}

return results;
```

## Common mistakes

- **Losing the N8N_ENCRYPTION_KEY and being unable to decrypt any saved credentials** — undefined Fix: Set N8N_ENCRYPTION_KEY explicitly in your environment variables and store a backup in a password manager. Never rely on the auto-generated key without backing it up.
- **Pasting API keys with leading or trailing whitespace or newline characters** — undefined Fix: Trim the key before pasting. Copy from the source, paste into a plain text editor first, remove any whitespace, then paste into n8n.
- **Adding auth headers manually in the HTTP Request node while also using a credential, sending the header twice** — undefined Fix: When using a credential, remove any manually added authentication headers from the node's Header Parameters section.
- **Using the same API credential for development and production workflows** — undefined Fix: Create separate credentials for each environment. Name them clearly: API Service - Dev and API Service - Prod.

## Best practices

- Always set N8N_ENCRYPTION_KEY explicitly in your environment variables and back it up separately from the database
- Name credentials descriptively, including the service and environment, for example: OpenAI - Production or Slack - Staging
- Use the Test button on credential forms whenever available to verify credentials before using them in workflows
- Never hardcode API keys in Code nodes or expressions — always use the credential system
- Rotate API keys periodically and update the corresponding n8n credentials immediately
- For team environments, use n8n's credential sharing feature to grant access without exposing the actual key values
- Use separate credentials for development and production to avoid accidental operations on live data
- Trim whitespace from API keys before pasting — invisible characters cause authentication failures

## Frequently asked questions

### Where does n8n store credentials?

n8n stores credentials in its database (SQLite by default or PostgreSQL if configured), encrypted using the N8N_ENCRYPTION_KEY. The raw API keys are never stored in plain text.

### Can I export and import credentials between n8n instances?

Credentials are exported as part of workflow JSON files, but only as references. The actual secret values are not included in exports for security. You need to re-enter credential values on the new instance.

### What happens if my API key expires?

Workflows using the expired credential will fail with authentication errors (usually 401). Open the credential in n8n, update it with the new key, save, and re-test. Active workflows will use the updated key automatically on the next execution.

### Can I share credentials with other n8n users?

Yes, in n8n's team features, you can share credentials with specific users. Open the credential, go to the Sharing tab, and add users. They can use the credential in their workflows without seeing the actual secret values.

### What is the difference between Header Auth and Query Auth credentials?

Header Auth adds your API key as an HTTP header (e.g., X-API-Key: your-key). Query Auth adds it as a URL query parameter (e.g., ?api_key=your-key). Use whichever method your API requires — most modern APIs use Header Auth.

### Can I use OAuth2 for custom APIs?

Yes, n8n has a Generic OAuth2 API credential type. Configure the Authorization URL, Access Token URL, Client ID, Client Secret, and scope. n8n handles the OAuth2 flow including token refresh.

### How do I fix 'Credentials not found' errors?

This usually happens when a workflow references a credential that was deleted or not shared with your user account. Recreate the credential with the same type and name, or ask the credential owner to share it with you.

### Can RapidDev help set up secure credential management for my n8n instance?

Yes, RapidDev can configure credential management best practices for your n8n deployment, including encryption key management, credential sharing policies, and integration with external secret stores.

---

Source: https://www.rapidevelopers.com/n8n-tutorial/how-to-add-custom-credentials-in-n8n
© RapidDev — https://www.rapidevelopers.com/n8n-tutorial/how-to-add-custom-credentials-in-n8n