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.
Prerequisites
- 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
Open the Credentials panel and create a new credential
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.
Fill in the credential fields for a built-in service
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.
Create a custom Header Auth credential for an unsupported API
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.
Use a custom credential with the HTTP Request node
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.
Understand credential encryption and the encryption key
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.
1# Set in docker-compose.yml to ensure persistence2environment:3 - N8N_ENCRYPTION_KEY=your-secure-random-string-here45# Or in .env file6N8N_ENCRYPTION_KEY=your-secure-random-string-here78# Generate a secure random key9openssl rand -hex 32Expected result: Your encryption key is explicitly set and backed up, ensuring credentials survive container or server changes.
Complete working example
1// Code node: Test API credentials by making a request2// This is useful when the built-in Test button is not available3// Place this Code node after an HTTP Request node to validate the response45const items = $input.all();6const results = [];78for (const item of items) {9 const statusCode = item.json.statusCode || item.json.$response?.statusCode;10 const body = item.json;1112 if (statusCode === 401 || statusCode === 403) {13 results.push({14 json: {15 credentialStatus: 'INVALID',16 error: 'Authentication failed. Check your API key or token.',17 statusCode: statusCode,18 suggestion: 'Verify the credential in n8n Settings → Credentials'19 }20 });21 } else if (statusCode >= 200 && statusCode < 300) {22 results.push({23 json: {24 credentialStatus: 'VALID',25 message: 'Credentials are working correctly',26 statusCode: statusCode27 }28 });29 } else {30 results.push({31 json: {32 credentialStatus: 'UNKNOWN',33 message: 'Unexpected response code',34 statusCode: statusCode,35 body: body36 }37 });38 }39}4041return results;Common mistakes when adding Custom Credentials in n8n
Why it's a problem: Losing the N8N_ENCRYPTION_KEY and being unable to decrypt any saved credentials
How to avoid: 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.
Why it's a problem: Pasting API keys with leading or trailing whitespace or newline characters
How to avoid: Trim the key before pasting. Copy from the source, paste into a plain text editor first, remove any whitespace, then paste into n8n.
Why it's a problem: Adding auth headers manually in the HTTP Request node while also using a credential, sending the header twice
How to avoid: When using a credential, remove any manually added authentication headers from the node's Header Parameters section.
Why it's a problem: Using the same API credential for development and production workflows
How to avoid: 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
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I need to connect n8n to a custom REST API that uses an X-API-Key header for authentication. Walk me through creating a Header Auth credential in n8n and using it with the HTTP Request node to make GET and POST requests.
Create a workflow with an HTTP Request node that calls a custom API endpoint using Header Auth credentials. Add a Code node to validate the response status and output whether the credentials are valid, invalid, or returning unexpected results.
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.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation