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

includeScopes

boolean

default:"false"

Include permission scopes in the response

includeData

boolean

default:"false"

Include credential data (encrypted fields will be redacted)

onlySharedWithMe

boolean

default:"false"

Only return credentials shared with you (excludes owned credentials)

includeGlobal

boolean

default:"true"

Include globally shared credentials

filter

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"

Response

data

array

Array of credential objects

string

Unique credential identifier

name

string

Credential name

type

string

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

isGlobal

boolean

Whether the credential is globally shared across all projects

isManaged

boolean

Whether the credential is managed by an external system

createdAt

string

ISO 8601 timestamp of creation

updatedAt

string

ISO 8601 timestamp of last update

scopes

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

credentialId

string

required

The credential ID

Query Parameters

includeData

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"

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

name

string

required

Credential name (1-128 characters)

type

string

required

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

data

object

required

Credential data with authentication fields specific to the credential type

projectId

string

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

isGlobal

boolean

default:"false"

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

isResolvable

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

credentialId

string

required

The credential ID to update

Request Body

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

name

string

Updated credential name

data

object

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

isGlobal

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

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

credentialId

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

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

credentials

object

required

Credential object to test

credentials.id

string

required

Credential ID

credentials.type

string

required

Credential type

credentials.data

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

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

credentialId

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

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

credentialId

string

required

The credential ID to transfer

Request Body

destinationProjectId

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

Generate Unique Name

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

GET /api/v1/credentials/new

Query Parameters

name

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"

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.

Enable Global Sharing Carefully

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

Core API

Node API

​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