# Credentials API Reference

Complete API reference for credential management operations. Understand n8n's security model and implement schema-driven credential creation.

---

## Overview

The Credentials API provides programmatic access to create and manage workflow credentials with strong security restrictions.

**Available Operations:**

| Operation | Purpose | Status | Notes |
|-----------|---------|--------|-------|
| `get_credential_schema` | Get credential type schema | ✅ Available | Essential for creation |
| `create_credential` | Create new credential | ✅ Available | Schema-driven |
| `delete_credential` | Remove credential | ✅ Available | Permanent |
| `list_credentials` | List credentials | ❌ Blocked | Security restriction |
| `get_credential` | Get credential data | ❌ Blocked | Security restriction |
| `update_credential` | Update credential | ⚠️ Workaround | Use DELETE + CREATE |

---

## Security Model

### n8n Credential Security (Epic 2)

n8n intentionally **blocks** LIST and GET operations for credentials via REST API to prevent credential exposure and unauthorized access.

**Security Architecture:**

```
Credentials in n8n Database
    ↓
Encrypted with AES-256
    ↓
REST API Blocks List/Get Operations
    ↓
Only n8n UI can view credentials
    ↓
MCP Server References by ID Only
```

**Blocked Operations:**

- ❌ `list_credentials` - Returns security guidance, not credential list
- ❌ `get_credential` - Returns security guidance, not credential data

**Why This Matters:**

1. **Prevents Credential Theft:** API cannot be used to extract credentials
2. **Reduces Attack Surface:** Limits credential access points
3. **Centralized Management:** Forces credential management through secure n8n UI
4. **Audit Trail:** All credential access logged in n8n

**Available Operations:**

- ✅ `get_credential_schema` - Get field requirements for credential types
- ✅ `create_credential` - Schema-driven creation with encrypted storage
- ✅ `delete_credential` - Permanent removal
- ⚠️ `update_credential` - Use DELETE + CREATE pattern (immutability)

**Recommended Approach:**

Manage credentials through n8n UI for visibility and control. Use MCP server only for programmatic creation of simple credential types.

---

## get_credential_schema

Retrieve JSON schema for a credential type to understand required fields and validation rules.

### Purpose

Get field requirements before creating credentials. Essential for schema-driven creation pattern and validation.

### Use Cases

- Understanding required fields for credential type
- Validating user input before credential creation
- Building credential creation UIs
- Documenting credential requirements

---

### Request

**MCP Tool Name:** `get_credential_schema`

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | Instance identifier |
| type | string | Yes | Credential type name |

**TypeScript Interface:**

```typescript
interface GetCredentialSchemaParams {
  instance?: string;
  type: string;
}
```

**Common Credential Types:**

```typescript
// Authentication
'httpBasicAuth'           // Basic HTTP authentication
'httpHeaderAuth'          // HTTP header authentication
'httpDigestAuth'          // Digest authentication
'oAuth1Api'               // OAuth 1.0
'oAuth2Api'               // OAuth 2.0

// Services
'googleSheetsOAuth2Api'   // Google Sheets
'slackApi'                // Slack
'slackOAuth2Api'          // Slack OAuth2
'gmailOAuth2'             // Gmail
'discordApi'              // Discord

// Databases
'postgresDb'              // PostgreSQL
'mysqlDb'                 // MySQL
'mongoDb'                 // MongoDB
'redis'                   // Redis

// And 100+ more types in n8n...
```

---

### Response

**TypeScript Interface:**

```typescript
interface CredentialSchema {
  type: 'object';
  properties: CredentialProperty[];
}

interface CredentialProperty {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'options';
  required: boolean;
  displayName: string;
  description?: string;
  default?: any;
  options?: PropertyOption[];
  placeholder?: string;
  typeOptions?: {
    password?: boolean;
    multipleValues?: boolean;
  };
}

interface PropertyOption {
  name: string;
  value: any;
}
```

---

### Response Examples

**httpBasicAuth Schema:**

```json
{
  "type": "object",
  "properties": [
    {
      "name": "user",
      "type": "string",
      "required": true,
      "displayName": "User",
      "description": "Username for basic authentication"
    },
    {
      "name": "password",
      "type": "string",
      "required": true,
      "displayName": "Password",
      "description": "Password for basic authentication",
      "typeOptions": {
        "password": true
      }
    }
  ]
}
```

**postgresDb Schema:**

```json
{
  "type": "object",
  "properties": [
    {
      "name": "host",
      "type": "string",
      "required": true,
      "displayName": "Host",
      "default": "localhost"
    },
    {
      "name": "port",
      "type": "number",
      "required": true,
      "displayName": "Database Port",
      "default": 5432
    },
    {
      "name": "database",
      "type": "string",
      "required": true,
      "displayName": "Database Name"
    },
    {
      "name": "user",
      "type": "string",
      "required": true,
      "displayName": "User"
    },
    {
      "name": "password",
      "type": "string",
      "required": true,
      "displayName": "Password",
      "typeOptions": {
        "password": true
      }
    },
    {
      "name": "ssl",
      "type": "options",
      "required": false,
      "displayName": "SSL",
      "options": [
        { "name": "Disable", "value": "disable" },
        { "name": "Allow", "value": "allow" },
        { "name": "Require", "value": "require" }
      ],
      "default": "disable"
    }
  ]
}
```

---

### Code Example

```typescript
// Get schema for HTTP Basic Auth
const schema = await callTool('get_credential_schema', {
  instance: 'production',
  type: 'httpBasicAuth'
});

const credSchema = JSON.parse(schema.content[0].text);

console.log('Required fields:');
credSchema.properties
  .filter(p => p.required)
  .forEach(p => {
    console.log(`  - ${p.name}: ${p.displayName}`);
    if (p.description) {
      console.log(`    ${p.description}`);
    }
  });

// Output:
// Required fields:
//   - user: User
//     Username for basic authentication
//   - password: Password
//     Password for basic authentication
```

---

## create_credential

Create new credential using schema-driven approach with encrypted storage.

### Purpose

Programmatically create credentials for workflow nodes. Credentials are encrypted and stored securely in n8n database.

### Use Cases

- CI/CD credential provisioning
- Bulk credential creation from templates
- Programmatic credential setup
- Testing and development environments

---

### Request

**MCP Tool Name:** `create_credential`

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | Instance identifier |
| name | string | Yes | Credential name (descriptive) |
| type | string | Yes | Credential type (from schema) |
| data | object | Yes | Credential data (schema-specific fields) |
| nodesAccess | object[] | No | Node access restrictions |

**TypeScript Interface:**

```typescript
interface CreateCredentialParams {
  instance?: string;
  name: string;
  type: string;
  data: Record<string, any>;
  nodesAccess?: NodeAccess[];
}

interface NodeAccess {
  nodeType: string;
}
```

---

### Schema-Driven Creation Pattern

**Step 1: Get Schema**

```typescript
const schemaResponse = await callTool('get_credential_schema', {
  type: 'httpBasicAuth',
  instance: 'production'
});

const schema = JSON.parse(schemaResponse.content[0].text);
```

**Step 2: Validate Data Against Schema**

```typescript
function validateCredentialData(
  data: Record<string, any>,
  schema: CredentialSchema
): void {
  // Check required fields
  const required = schema.properties
    .filter(p => p.required)
    .map(p => p.name);

  const missing = required.filter(field => !data[field]);

  if (missing.length > 0) {
    throw new Error(
      `Missing required fields: ${missing.join(', ')}`
    );
  }

  // Validate field types
  for (const prop of schema.properties) {
    if (data[prop.name] !== undefined) {
      const actualType = typeof data[prop.name];
      const expectedType = prop.type;

      if (expectedType === 'number' && actualType !== 'number') {
        throw new Error(
          `Field '${prop.name}' must be a number, got ${actualType}`
        );
      }

      if (expectedType === 'string' && actualType !== 'string') {
        throw new Error(
          `Field '${prop.name}' must be a string, got ${actualType}`
        );
      }
    }
  }
}

// Usage
validateCredentialData(credentialData, schema);
```

**Step 3: Create Credential**

```typescript
const credential = await callTool('create_credential', {
  instance: 'production',
  name: 'API Basic Auth',
  type: 'httpBasicAuth',
  data: {
    user: process.env.API_USER,
    password: process.env.API_PASSWORD
  }
});

const result = JSON.parse(credential.content[0].text);
console.log(`Created credential: ${result.id}`);
```

---

### Response

**Success Response:**

```typescript
interface CreateCredentialResponse {
  id: string;
  name: string;
  type: string;
  createdAt: string;
  updatedAt: string;
  nodesAccess?: NodeAccess[];
}
```

**Important:** `data` field is NEVER returned for security reasons.

**JSON Example:**

```json
{
  "id": "cred_abc123",
  "name": "API Basic Auth",
  "type": "httpBasicAuth",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}
```

---

### Complete Creation Examples

**HTTP Basic Auth:**

```typescript
// Step 1: Get schema
const schema = await callTool('get_credential_schema', {
  type: 'httpBasicAuth'
});

// Step 2: Create credential
const credential = await callTool('create_credential', {
  instance: 'production',
  name: 'External API Credentials',
  type: 'httpBasicAuth',
  data: {
    user: 'api_user',
    password: 'secure_password_here'
  }
});

const result = JSON.parse(credential.content[0].text);
console.log(`Credential ID: ${result.id}`);
```

**PostgreSQL Database:**

```typescript
const postgresCredential = await callTool('create_credential', {
  instance: 'production',
  name: 'Production Database',
  type: 'postgresDb',
  data: {
    host: 'db.example.com',
    port: 5432,
    database: 'production_db',
    user: 'dbuser',
    password: process.env.DB_PASSWORD,
    ssl: 'require'
  }
});
```

**Slack API:**

```typescript
const slackCredential = await callTool('create_credential', {
  instance: 'production',
  name: 'Slack Bot Token',
  type: 'slackApi',
  data: {
    accessToken: process.env.SLACK_BOT_TOKEN
  }
});
```

---

## UPDATE Pattern (DELETE + CREATE)

n8n does not support direct credential updates due to security and immutability.

**Workaround:** Delete old credential and create new one.

```typescript
async function updateCredential(
  credentialId: string,
  newData: CreateCredentialParams,
  instance?: string
): Promise<CreateCredentialResponse> {
  console.log(`Updating credential ${credentialId}...`);

  // Step 1: Delete old credential
  await callTool('delete_credential', {
    id: credentialId,
    instance
  });
  console.log('Old credential deleted');

  // Step 2: Create new credential with updated data
  const newCredential = await callTool('create_credential', {
    ...newData,
    instance
  });

  const result = JSON.parse(newCredential.content[0].text);

  console.log(`Credential updated: ${credentialId} → ${result.id}`);
  console.log('⚠️  Note: Credential ID changed. Update workflow references!');

  return result;
}

// Usage
const updated = await updateCredential(
  'cred_old123',
  {
    name: 'API Basic Auth',
    type: 'httpBasicAuth',
    data: {
      user: 'new_user',
      password: 'new_password'
    }
  },
  'production'
);
```

**Important:** Workflows using old credential ID will break. Update workflow credential references after recreation:

```typescript
async function updateWorkflowCredentials(
  workflowId: string,
  oldCredentialId: string,
  newCredentialId: string,
  instance?: string
): Promise<void> {
  // Get workflow
  const workflow = await callTool('get_workflow', {
    id: workflowId,
    instance
  });

  const wf = JSON.parse(workflow.content[0].text);

  // Update credential references
  wf.nodes.forEach(node => {
    if (node.credentials) {
      for (const [type, cred] of Object.entries(node.credentials)) {
        if (cred.id === oldCredentialId) {
          cred.id = newCredentialId;
          console.log(`Updated credential in node: ${node.name}`);
        }
      }
    }
  });

  // Save workflow
  await callTool('update_workflow', {
    id: workflowId,
    instance,
    nodes: wf.nodes
  });

  console.log(`Workflow ${workflowId} credential references updated`);
}
```

---

## delete_credential

Remove credential permanently from instance.

### Request

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instance | string | No | Instance identifier |
| id | string | Yes | Credential ID to delete |

### Code Example

```typescript
await callTool('delete_credential', {
  instance: 'staging',
  id: 'cred_test123'
});

console.log('Credential deleted successfully');
```

**Warning:**
- Deletion is permanent and cannot be undone
- Workflows using this credential will fail
- Remove credential references from workflows first

---

## list_credentials

**Status:** ❌ Blocked by n8n API for security

### Security Guidance

This operation is intentionally blocked by n8n's REST API to prevent credential exposure.

**What Happens:**

```typescript
const response = await callTool('list_credentials', {
  instance: 'production'
});

// Returns security guidance, not credentials
```

**Response:**

```json
{
  "message": "Credential listing is blocked by n8n API for security.",
  "reason": "Credentials are encrypted and should only be managed through n8n UI",
  "recommendation": "Use n8n web interface to view and manage credentials",
  "alternatives": [
    "View credentials in n8n UI: Settings → Credentials",
    "Track credential IDs during creation",
    "Use credential references by ID in workflows"
  ]
}
```

---

## get_credential

**Status:** ❌ Blocked by n8n API for security

### Security Guidance

This operation is intentionally blocked to prevent credential data exposure.

**What Happens:**

```typescript
const response = await callTool('get_credential', {
  id: 'cred_123',
  instance: 'production'
});

// Returns security guidance, not credential data
```

**Alternatives:**

1. **View in n8n UI:** Settings → Credentials → Select credential
2. **Track During Creation:** Store credential IDs when created
3. **Reference by ID:** Use credential ID in workflow nodes

---

## Best Practices

### 1. Never Hardcode Credentials

```typescript
// ❌ Bad: Hardcoded credentials in code
const cred = await callTool('create_credential', {
  type: 'httpBasicAuth',
  data: {
    user: 'admin',
    password: 'password123'  // NEVER do this!
  }
});

// ✅ Good: Use environment variables
const cred = await callTool('create_credential', {
  type: 'httpBasicAuth',
  data: {
    user: process.env.API_USER,
    password: process.env.API_PASSWORD
  }
});

// ✅ Good: Load from secure vault
import { getSecret } from './secure-vault';

const cred = await callTool('create_credential', {
  type: 'httpBasicAuth',
  data: {
    user: await getSecret('api_user'),
    password: await getSecret('api_password')
  }
});
```

### 2. Always Use Schema Validation

```typescript
// ✅ Good: Schema-driven creation
async function createValidatedCredential(
  type: string,
  name: string,
  data: Record<string, any>,
  instance?: string
) {
  // Get schema
  const schemaResponse = await callTool('get_credential_schema', {
    type,
    instance
  });
  const schema = JSON.parse(schemaResponse.content[0].text);

  // Validate
  validateCredentialData(data, schema);

  // Create
  return await callTool('create_credential', {
    instance,
    name,
    type,
    data
  });
}

// ❌ Bad: Guessing fields without schema
const cred = await callTool('create_credential', {
  type: 'unknownType',
  data: {
    field1: 'value',  // May be wrong!
    field2: 'value'   // May be missing required fields!
  }
});
```

### 3. Manage Complex Credentials via UI

For OAuth2, JWT, and other complex credential types:

```typescript
// ✅ Recommended: Use n8n UI for complex types
// - OAuth2 with multiple steps
// - JWT with key generation
// - Service accounts with JSON key files
// - SSH keys

// ✅ Good: Use MCP for simple types
// - HTTP Basic Auth
// - API keys
// - Database credentials
// - Simple tokens
```

### 4. Track Credential IDs

```typescript
// ✅ Good: Track credential IDs for reference
const credentialRegistry: Record<string, string> = {};

async function createAndTrackCredential(
  name: string,
  type: string,
  data: Record<string, any>,
  instance?: string
) {
  const response = await callTool('create_credential', {
    instance,
    name,
    type,
    data
  });

  const credential = JSON.parse(response.content[0].text);

  // Track for later reference
  const key = `${instance || 'default'}-${name}`;
  credentialRegistry[key] = credential.id;

  console.log(`Created and tracked: ${key} → ${credential.id}`);

  return credential;
}

// Later: retrieve credential ID
const credId = credentialRegistry['production-API Basic Auth'];
```

### 5. Secure Credential Lifecycle

```typescript
// Complete secure credential lifecycle
async function secureCredentialLifecycle() {
  // 1. Get schema
  const schema = await callTool('get_credential_schema', {
    type: 'httpBasicAuth'
  });

  // 2. Load secrets from secure vault (never hardcode!)
  const secrets = await loadSecretsFromVault();

  // 3. Validate against schema
  validateCredentialData(secrets, schema);

  // 4. Create credential
  const credential = await callTool('create_credential', {
    instance: 'production',
    name: 'Secure API Credentials',
    type: 'httpBasicAuth',
    data: secrets
  });

  // 5. Track credential ID (don't track data!)
  saveCredentialId(credential.id);

  // 6. Clear secrets from memory
  Object.keys(secrets).forEach(key => delete secrets[key]);

  // 7. Use in workflows by reference
  return credential.id;
}
```

---

## Next Steps

- **[Workflows API Reference](workflows-api.md)** - Use credentials in workflows
- **[Tags API Reference](tags-api.md)** - Organize credentials with tags
- **[Security Best Practices](../features/credentials-security.md)** - Credential security guide
- **[API Architecture](overview.md)** - Security architecture details

---

**Document Version:** 1.0
**Last Updated:** January 2025
**Related Epic:** Epic 2 (Credentials API Implementation)
**Security Note:** Always follow security best practices when handling credentials