> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/n8n-io/n8n/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials API

> Manage authentication credentials for workflow nodes using the n8n REST 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.

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

## List Credentials

Retrieve a list of credentials accessible to your account.

```http theme={null}
GET /api/v1/credentials
```

### Query Parameters

<ParamField query="includeScopes" type="boolean" default="false">
  Include permission scopes in the response
</ParamField>

<ParamField query="includeData" type="boolean" default="false">
  Include credential data (encrypted fields will be redacted)
</ParamField>

<ParamField query="onlySharedWithMe" type="boolean" default="false">
  Only return credentials shared with you (excludes owned credentials)
</ParamField>

<ParamField query="includeGlobal" type="boolean" default="true">
  Include globally shared credentials
</ParamField>

<ParamField query="filter" type="object">
  Filter credentials by various criteria
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-N8N-API-KEY: your-api-key" \
    "https://your-n8n-instance.com/api/v1/credentials?includeScopes=true"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### Response

<ResponseField name="data" type="array">
  Array of credential objects

  <ResponseField name="id" type="string">
    Unique credential identifier
  </ResponseField>

  <ResponseField name="name" type="string">
    Credential name
  </ResponseField>

  <ResponseField name="type" type="string">
    Credential type (e.g., "googleSheetsOAuth2Api", "httpBasicAuth")
  </ResponseField>

  <ResponseField name="isGlobal" type="boolean">
    Whether the credential is globally shared across all projects
  </ResponseField>

  <ResponseField name="isManaged" type="boolean">
    Whether the credential is managed by an external system
  </ResponseField>

  <ResponseField name="createdAt" type="string">
    ISO 8601 timestamp of creation
  </ResponseField>

  <ResponseField name="updatedAt" type="string">
    ISO 8601 timestamp of last update
  </ResponseField>

  <ResponseField name="scopes" type="string[]">
    Permission scopes (only if `includeScopes=true`)
  </ResponseField>
</ResponseField>

```json Example Response theme={null}
[
  {
    "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.

```http theme={null}
GET /api/v1/credentials/:credentialId
```

### Path Parameters

<ParamField path="credentialId" type="string" required>
  The credential ID
</ParamField>

### Query Parameters

<ParamField query="includeData" type="boolean" default="false">
  Include credential data (sensitive fields will be redacted)
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-N8N-API-KEY: your-api-key" \
    "https://your-n8n-instance.com/api/v1/credentials/cred_123?includeData=true"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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"]
}
```

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

## Create Credential

Create a new credential.

```http theme={null}
POST /api/v1/credentials
```

### Request Body

<ParamField body="name" type="string" required>
  Credential name (1-128 characters)
</ParamField>

<ParamField body="type" type="string" required>
  Credential type identifier (e.g., "httpBasicAuth", "googleSheetsOAuth2Api")
</ParamField>

<ParamField body="data" type="object" required>
  Credential data with authentication fields specific to the credential type
</ParamField>

<ParamField body="projectId" type="string">
  Project ID to create credential in (defaults to personal project)
</ParamField>

<ParamField body="isGlobal" type="boolean" default="false">
  Whether to share the credential globally across all projects (requires permission)
</ParamField>

<ParamField body="isResolvable" type="boolean" default="false">
  Whether the credential uses dynamic resolution (Enterprise feature)
</ParamField>

### Example Request

<Tabs>
  <Tab title="HTTP Basic Auth">
    <CodeGroup>
      ```bash cURL theme={null}
      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
      ```
    </CodeGroup>
  </Tab>

  <Tab title="API Key">
    <CodeGroup>
      ```bash cURL theme={null}
      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
      ```
    </CodeGroup>
  </Tab>

  <Tab title="OAuth2">
    <CodeGroup>
      ```javascript JavaScript theme={null}
      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();
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Response

Returns the created credential object:

```json theme={null}
{
  "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"]
}
```

<Warning>
  The credential `data` is not returned in the response for security. The data is encrypted and stored securely.
</Warning>

## Update Credential

Update an existing credential.

```http theme={null}
PATCH /api/v1/credentials/:credentialId
```

### Path Parameters

<ParamField path="credentialId" type="string" required>
  The credential ID to update
</ParamField>

### Request Body

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

<ParamField body="name" type="string">
  Updated credential name
</ParamField>

<ParamField body="data" type="object">
  Updated credential data. You must provide all fields, not just changed ones.
</ParamField>

<ParamField body="isGlobal" type="boolean">
  Update global sharing status (requires permission)
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

### Response

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

<Note>
  When updating credential `data`, you must provide the complete data object. Partial updates are not supported for the data field.
</Note>

## Delete Credential

Permanently delete a credential.

```http theme={null}
DELETE /api/v1/credentials/:credentialId
```

### Path Parameters

<ParamField path="credentialId" type="string" required>
  The credential ID to delete
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE \
    -H "X-N8N-API-KEY: your-api-key" \
    https://your-n8n-instance.com/api/v1/credentials/cred_789
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

### Response

```json theme={null}
true
```

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

## Test Credential

Test if a credential configuration is valid.

```http theme={null}
POST /api/v1/credentials/test
```

### Request Body

<ParamField body="credentials" type="object" required>
  Credential object to test

  <ParamField body="credentials.id" type="string" required>
    Credential ID
  </ParamField>

  <ParamField body="credentials.type" type="string" required>
    Credential type
  </ParamField>

  <ParamField body="credentials.data" type="object">
    Credential data (can be partial for testing changes)
  </ParamField>
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

### Response

<Tabs>
  <Tab title="Success">
    ```json theme={null}
    {
      "status": "success",
      "message": "Connection successful"
    }
    ```
  </Tab>

  <Tab title="Failure">
    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid credentials: Authentication failed"
    }
    ```
  </Tab>
</Tabs>

## Share Credential

Share a credential with other projects.

```http theme={null}
PUT /api/v1/credentials/:credentialId/share
```

### Path Parameters

<ParamField path="credentialId" type="string" required>
  The credential ID to share
</ParamField>

### Request Body

<ParamField body="shareWithIds" type="string[]" required>
  Array of project IDs to share the credential with
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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']
      })
    }
  );
  ```
</CodeGroup>

### Response

Returns `204 No Content` on success.

<Note>
  Sharing credentials requires the `credential:share` permission and an Enterprise license.
</Note>

## Transfer Credential

Transfer a credential to a different project.

```http theme={null}
PUT /api/v1/credentials/:credentialId/transfer
```

### Path Parameters

<ParamField path="credentialId" type="string" required>
  The credential ID to transfer
</ParamField>

### Request Body

<ParamField body="destinationProjectId" type="string" required>
  The target project ID
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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'
      })
    }
  );
  ```
</CodeGroup>

## Generate Unique Name

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

```http theme={null}
GET /api/v1/credentials/new
```

### Query Parameters

<ParamField query="name" type="string">
  Base name for the credential. If not provided, uses the default "My credentials".
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-N8N-API-KEY: your-api-key" \
    "https://your-n8n-instance.com/api/v1/credentials/new?name=API%20Key"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "name": "API Key 3"
}
```

<Note>
  If credentials with the requested name exist, a number is appended (e.g., "API Key 2", "API Key 3").
</Note>

## Credential Types

Common credential types in n8n:

<AccordionGroup>
  <Accordion title="HTTP Authentication">
    * `httpBasicAuth` - Basic authentication
    * `httpDigestAuth` - Digest authentication
    * `httpHeaderAuth` - Header-based authentication
    * `httpQueryAuth` - Query parameter authentication
    * `oAuth1Api` - OAuth 1.0
    * `oAuth2Api` - OAuth 2.0
  </Accordion>

  <Accordion title="Database Credentials">
    * `postgres` - PostgreSQL
    * `mysql` - MySQL/MariaDB
    * `mongoDb` - MongoDB
    * `redis` - Redis
    * `microsoftSql` - Microsoft SQL Server
  </Accordion>

  <Accordion title="Cloud Services">
    * `aws` - Amazon Web Services
    * `googleApi` - Google Cloud Platform
    * `azureApi` - Microsoft Azure
  </Accordion>

  <Accordion title="SaaS Applications">
    * `slackApi` - Slack
    * `githubApi` - GitHub
    * `googleSheetsOAuth2Api` - Google Sheets
    * `salesforceOAuth2Api` - Salesforce
    * `notionApi` - Notion
  </Accordion>
</AccordionGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use Least Privilege">
    Grant credentials only the minimum permissions required for workflows to function.
  </Accordion>

  <Accordion title="Rotate Credentials Regularly">
    Update API keys and passwords periodically to reduce security risks.
  </Accordion>

  <Accordion title="Audit Credential Usage">
    Regularly review which workflows use each credential and remove unused credentials.
  </Accordion>

  <Accordion title="Enable Global Sharing Carefully">
    Only mark credentials as global if they truly need to be accessible across all projects.
  </Accordion>

  <Accordion title="Test Before Deploying">
    Always test credentials in a development environment before using them in production workflows.
  </Accordion>

  <Accordion title="Monitor for Leaks">
    Ensure credentials are never logged or exposed in workflow outputs.
  </Accordion>
</AccordionGroup>

## Common Patterns

### Programmatic Credential Rotation

<CodeGroup>
  ```javascript Rotate API Key theme={null}
  // 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');
  ```
</CodeGroup>

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "message": "Managed credentials cannot be updated"
}
```

### 403 Forbidden

```json theme={null}
{
  "message": "You do not have permission to change global sharing for credentials"
}
```

### 404 Not Found

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Workflows API" icon="diagram-project" href="/api/workflows">
    Use credentials in workflows
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn about API authentication
  </Card>

  <Card title="Security" icon="shield" href="/security/credentials">
    Credential security best practices
  </Card>

  <Card title="Node Credentials" icon="plug" href="/integrations/credentials">
    Learn about node credential types
  </Card>
</CardGroup>