Credentials API

Overview

The Credentials API allows you to programmatically manage credentials used by workflow nodes for authentication. Credentials store sensitive information like API keys, OAuth tokens, and database passwords securely.

Credentials contain sensitive data. Always use secure connections (HTTPS) and handle credentials with appropriate security measures.

List Credentials

Retrieve a list of credentials accessible to your account.

GET /api/v1/credentials

Query Parameters

boolean

default:"false"

Include permission scopes in the response

boolean

default:"false"

Include credential data (encrypted fields will be redacted)

boolean

default:"false"

Only return credentials shared with you (excludes owned credentials)

boolean

default:"true"

Include globally shared credentials

object

Filter credentials by various criteria

Example Request

curl -H "X-N8N-API-KEY: your-api-key" \
  "https://your-n8n-instance.com/api/v1/credentials?includeScopes=true"

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials?includeScopes=true',
  {
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const credentials = await response.json();

import requests

response = requests.get(
    'https://your-n8n-instance.com/api/v1/credentials',
    headers={'X-N8N-API-KEY': 'your-api-key'},
    params={'includeScopes': True}
)

credentials = response.json()

Response

array

Array of credential objects

string

Unique credential identifier

string

Credential name

string

Credential type (e.g., “googleSheetsOAuth2Api”, “httpBasicAuth”)

boolean

Whether the credential is globally shared across all projects

boolean

Whether the credential is managed by an external system

string

ISO 8601 timestamp of creation

string

ISO 8601 timestamp of last update

string[]

Permission scopes (only if includeScopes=true)

Example Response

[
  {
    "id": "cred_123",
    "name": "Google Sheets Account",
    "type": "googleSheetsOAuth2Api",
    "isGlobal": false,
    "isManaged": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-02-10T14:20:00.000Z",
    "scopes": ["credential:read", "credential:update"]
  },
  {
    "id": "cred_456",
    "name": "Slack API Key",
    "type": "slackApi",
    "isGlobal": true,
    "isManaged": false,
    "createdAt": "2024-01-20T09:15:00.000Z",
    "updatedAt": "2024-01-20T09:15:00.000Z",
    "scopes": ["credential:read"]
  }
]

Get Credential

Retrieve details of a specific credential.

GET /api/v1/credentials/:credentialId

Path Parameters

string

required

The credential ID

Query Parameters

boolean

default:"false"

Include credential data (sensitive fields will be redacted)

Example Request

curl -H "X-N8N-API-KEY: your-api-key" \
  "https://your-n8n-instance.com/api/v1/credentials/cred_123?includeData=true"

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/cred_123?includeData=true',
  {
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const credential = await response.json();

Response

{
  "id": "cred_123",
  "name": "Google Sheets Account",
  "type": "googleSheetsOAuth2Api",
  "data": {
    "clientId": "123456789.apps.googleusercontent.com",
    "clientSecret": "***REDACTED***",
    "oauthTokenData": "***REDACTED***"
  },
  "isGlobal": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-02-10T14:20:00.000Z",
  "scopes": ["credential:read", "credential:update"]
}

Sensitive credential fields are automatically redacted with ***REDACTED*** even when includeData=true. This protects secrets while allowing you to verify credential configuration.

Create Credential

Create a new credential.

POST /api/v1/credentials

Request Body

string

required

Credential name (1-128 characters)

string

required

Credential type identifier (e.g., “httpBasicAuth”, “googleSheetsOAuth2Api”)

object

required

Credential data with authentication fields specific to the credential type

string

Project ID to create credential in (defaults to personal project)

boolean

default:"false"

Whether to share the credential globally across all projects (requires permission)

boolean

default:"false"

Whether the credential uses dynamic resolution (Enterprise feature)

Example Request

HTTP Basic Auth
API Key
OAuth2

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Credentials",
    "type": "httpBasicAuth",
    "data": {
      "user": "api_user",
      "password": "secret_password"
    }
  }' \
  https://your-n8n-instance.com/api/v1/credentials

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack API",
    "type": "slackApi",
    "data": {
      "accessToken": "xoxb-your-slack-token"
    }
  }' \
  https://your-n8n-instance.com/api/v1/credentials

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials',
  {
    method: 'POST',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Google Sheets OAuth',
      type: 'googleSheetsOAuth2Api',
      data: {
        clientId: '123456.apps.googleusercontent.com',
        clientSecret: 'your_client_secret',
        scope: 'https://www.googleapis.com/auth/spreadsheets'
      }
    })
  }
);

const credential = await response.json();

Response

Returns the created credential object:

{
  "id": "cred_789",
  "name": "My API Credentials",
  "type": "httpBasicAuth",
  "isGlobal": false,
  "isManaged": false,
  "createdAt": "2024-02-19T14:30:00.000Z",
  "updatedAt": "2024-02-19T14:30:00.000Z",
  "scopes": ["credential:read", "credential:update", "credential:delete"]
}

The credential data is not returned in the response for security. The data is encrypted and stored securely.

Update Credential

Update an existing credential.

PATCH /api/v1/credentials/:credentialId

Path Parameters

string

required

The credential ID to update

Request Body

All fields are optional. Only include fields you want to update.

string

Updated credential name

object

Updated credential data. You must provide all fields, not just changed ones.

boolean

Update global sharing status (requires permission)

Example Request

curl -X PATCH \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated API Credentials",
    "data": {
      "user": "api_user",
      "password": "new_secret_password"
    }
  }' \
  https://your-n8n-instance.com/api/v1/credentials/cred_789

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/cred_789',
  {
    method: 'PATCH',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Updated API Credentials',
      data: {
        user: 'api_user',
        password: 'new_secret_password'
      }
    })
  }
);

const updated = await response.json();

Response

{
  "id": "cred_789",
  "name": "Updated API Credentials",
  "type": "httpBasicAuth",
  "updatedAt": "2024-02-19T15:00:00.000Z",
  "scopes": ["credential:read", "credential:update", "credential:delete"]
}

When updating credential data, you must provide the complete data object. Partial updates are not supported for the data field.

Delete Credential

Permanently delete a credential.

DELETE /api/v1/credentials/:credentialId

Path Parameters

string

required

The credential ID to delete

Example Request

curl -X DELETE \
  -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/credentials/cred_789

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/cred_789',
  {
    method: 'DELETE',
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const result = await response.json();

Response

true

Deleting a credential will cause workflows using it to fail. Ensure no active workflows depend on the credential before deletion.

Test Credential

Test if a credential configuration is valid.

POST /api/v1/credentials/test

Request Body

object

required

Credential object to test

string

required

Credential ID

string

required

Credential type

object

Credential data (can be partial for testing changes)

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "id": "cred_123",
      "type": "googleSheetsOAuth2Api",
      "data": {}
    }
  }' \
  https://your-n8n-instance.com/api/v1/credentials/test

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/test',
  {
    method: 'POST',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      credentials: {
        id: 'cred_123',
        type: 'googleSheetsOAuth2Api',
        data: {}
      }
    })
  }
);

const testResult = await response.json();

Response

Success
Failure

{
  "status": "success",
  "message": "Connection successful"
}

{
  "status": "error",
  "message": "Invalid credentials: Authentication failed"
}

Share a credential with other projects.

PUT /api/v1/credentials/:credentialId/share

Path Parameters

string

required

The credential ID to share

Request Body

Array of project IDs to share the credential with

Example Request

curl -X PUT \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "shareWithIds": ["project_abc", "project_def"]
  }' \
  https://your-n8n-instance.com/api/v1/credentials/cred_123/share

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/cred_123/share',
  {
    method: 'PUT',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      shareWithIds: ['project_abc', 'project_def']
    })
  }
);

Response

Returns 204 No Content on success.

Sharing credentials requires the credential:share permission and an Enterprise license.

Transfer Credential

Transfer a credential to a different project.

PUT /api/v1/credentials/:credentialId/transfer

Path Parameters

string

required

The credential ID to transfer

Request Body

string

required

The target project ID

Example Request

curl -X PUT \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationProjectId": "project_xyz"
  }' \
  https://your-n8n-instance.com/api/v1/credentials/cred_123/transfer

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/cred_123/transfer',
  {
    method: 'PUT',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      destinationProjectId: 'project_xyz'
    })
  }
);

Generate Unique Name

Generate a unique credential name (useful when creating credentials).

GET /api/v1/credentials/new

Query Parameters

string

Base name for the credential. If not provided, uses the default “My credentials”.

Example Request

curl -H "X-N8N-API-KEY: your-api-key" \
  "https://your-n8n-instance.com/api/v1/credentials/new?name=API%20Key"

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/new?name=API%20Key',
  { headers: { 'X-N8N-API-KEY': 'your-api-key' } }
);

const { name } = await response.json();
console.log('Suggested name:', name);

Response

{
  "name": "API Key 3"
}

If credentials with the requested name exist, a number is appended (e.g., “API Key 2”, “API Key 3”).

Credential Types

Common credential types in n8n:

HTTP Authentication

httpBasicAuth - Basic authentication
httpDigestAuth - Digest authentication
httpHeaderAuth - Header-based authentication
httpQueryAuth - Query parameter authentication
oAuth1Api - OAuth 1.0
oAuth2Api - OAuth 2.0

Database Credentials

postgres - PostgreSQL
mysql - MySQL/MariaDB
mongoDb - MongoDB
redis - Redis
microsoftSql - Microsoft SQL Server

Cloud Services

aws - Amazon Web Services
googleApi - Google Cloud Platform
azureApi - Microsoft Azure

SaaS Applications

slackApi - Slack
githubApi - GitHub
googleSheetsOAuth2Api - Google Sheets
salesforceOAuth2Api - Salesforce
notionApi - Notion

Security Best Practices

Use Least Privilege

Grant credentials only the minimum permissions required for workflows to function.

Rotate Credentials Regularly

Update API keys and passwords periodically to reduce security risks.

Audit Credential Usage

Regularly review which workflows use each credential and remove unused credentials.

Test Before Deploying

Always test credentials in a development environment before using them in production workflows.

Monitor for Leaks

Ensure credentials are never logged or exposed in workflow outputs.

Common Patterns

Programmatic Credential Rotation

// 1. Get current credential
const current = await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/cred_123?includeData=true',
  { headers: { 'X-N8N-API-KEY': 'your-api-key' } }
).then(r => r.json());

// 2. Generate new API key from external service
const newApiKey = await generateNewApiKey();

// 3. Update credential
await fetch(
  'https://your-n8n-instance.com/api/v1/credentials/cred_123',
  {
    method: 'PATCH',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      data: {
        ...current.data,
        apiKey: newApiKey
      }
    })
  }
);

console.log('Credential rotated successfully');

Error Responses

400 Bad Request

{
  "message": "Managed credentials cannot be updated"
}

403 Forbidden

{
  "message": "You do not have permission to change global sharing for credentials"
}

404 Not Found

{
  "message": "Credential to be deleted not found. You can only removed credentials owned by you"
}

Next Steps

Workflows API

Use credentials in workflows

Authentication

Learn about API authentication

Security

Credential security best practices

Node Credentials

Learn about node credential types

​Overview

​List Credentials

​Query Parameters

​Example Request

​Response

​Get Credential

​Path Parameters

​Query Parameters

​Example Request

​Response

​Create Credential

​Request Body

​Example Request

​Response

​Update Credential

​Path Parameters

​Request Body

​Example Request

​Response

​Delete Credential

​Path Parameters

​Example Request

​Response

​Test Credential

​Request Body

​Example Request

​Response

​Share Credential

​Path Parameters

​Request Body

​Example Request

​Response

​Transfer Credential

​Path Parameters

​Request Body

​Example Request

​Generate Unique Name

​Query Parameters

​Example Request

​Response

​Credential Types

​Security Best Practices

​Common Patterns

​Programmatic Credential Rotation

​Error Responses

​400 Bad Request

​403 Forbidden

​404 Not Found

​Next Steps

Workflows API

Authentication

Security

Node Credentials

Overview

List Credentials

Query Parameters

Example Request

Response

Get Credential

Path Parameters

Query Parameters

Example Request

Response

Create Credential

Request Body

Example Request

Response

Update Credential

Path Parameters

Request Body

Example Request

Response

Delete Credential

Path Parameters

Example Request

Response

Test Credential

Request Body

Example Request

Response

Share Credential

Path Parameters

Request Body

Example Request

Response

Transfer Credential

Path Parameters

Request Body

Example Request

Generate Unique Name

Query Parameters

Example Request

Response

Credential Types

Security Best Practices

Common Patterns

Programmatic Credential Rotation

Error Responses

400 Bad Request

403 Forbidden

404 Not Found

Next Steps