# Story 2.6.3: Implement POST /credentials
<!-- Powered by BMAD™ Core -->
## Status
**Draft**
## Story
**As a** workflow automation user,
**I want** to create new credentials for external service integrations through the MCP server,
**so that** I can configure authentication for workflows programmatically without manual UI interaction.
## Acceptance Criteria
1. New `create_credential` MCP tool registered and functional
2. Tool supports multiple credential types (OAuth2, API Key, Basic Auth, etc.)
3. Request body validation for required fields
4. Security: Sensitive data encrypted by n8n automatically
5. Response returns created credential with ID
6. Multi-instance routing works correctly
7. Error handling for invalid credential data (400)
8. Type-specific validation based on credential schema
9. Documentation with credential type examples
10. Comprehensive testing with multiple types
## Tasks / Subtasks
### Task 1: Study Credential Schemas (AC: 2, 8)
- [ ] Research common credential types and schemas
- [ ] Document required fields per type
- [ ] Understand type-specific validation
- [ ] Note OAuth2 vs API Key vs Basic Auth differences
- [ ] Create credential type reference
### Task 2: Implement createCredential (AC: 1, 2, 6)
- [ ] Add `createCredential` method to N8NApiWrapper
- [ ] Use callWithInstance pattern
- [ ] Support credential object parameter
- [ ] Add validation and error handling
- [ ] Follow existing patterns
### Task 3: Register create_credential Tool (AC: 1)
- [ ] Add tool definition to src/index.ts
- [ ] Define input schema with credential structure
- [ ] Support multiple credential types
- [ ] Add comprehensive description
- [ ] Include security notes
### Task 4: Validation Logic (AC: 3, 8)
- [ ] Validate required fields (name, type, data)
- [ ] Type-specific validation
- [ ] Data structure validation
- [ ] Error message clarity
### Task 5: Create Tests (AC: 10)
- [ ] **Test 5.1**: Create HTTP Basic Auth credential
- [ ] Simple username/password
- [ ] Verify creation success
- [ ] Check returned ID
- [ ] **Test 5.2**: Create API Key credential
- [ ] Single API key field
- [ ] Verify data structure
- [ ] **Test 5.3**: Create OAuth2 credential
- [ ] Complex OAuth2 fields
- [ ] Verify all fields accepted
- [ ] **Test 5.4**: Create custom credential
- [ ] Custom type with multiple fields
- [ ] **Test 5.5**: Multi-instance creation
- [ ] Create in different instances
- [ ] Verify isolation
- [ ] **Test 5.6**: Validation errors
- [ ] Missing required fields (400)
- [ ] Invalid credential type
- [ ] Malformed data structure
- [ ] **Test 5.7**: Security verification
- [ ] Verify data encrypted at rest
- [ ] Check sensitive data handling
### Task 6: Documentation (AC: 9)
- [ ] Add credential creation examples
- [ ] Document common credential types
- [ ] Security best practices
- [ ] Update README and CHANGELOG
### Task 7: Integration
- [ ] Add to test suite
- [ ] Create credential fixtures
- [ ] Cleanup utilities
## Dev Notes
### Credential Creation Request
```typescript
{
name: string; // User-defined name
type: string; // Credential type
data: { // Type-specific data
[key: string]: any; // Varies by type
}
}
```
### Common Credential Types
**HTTP Basic Auth:**
```json
{
"name": "My Basic Auth",
"type": "httpBasicAuth",
"data": {
"user": "username",
"password": "password123"
}
}
```
**HTTP Header Auth:**
```json
{
"name": "API Key Auth",
"type": "httpHeaderAuth",
"data": {
"name": "X-API-Key",
"value": "abc123xyz"
}
}
```
**OAuth2:**
```json
{
"name": "Google OAuth2",
"type": "googleOAuth2Api",
"data": {
"clientId": "client_id",
"clientSecret": "client_secret",
"accessToken": "token",
"refreshToken": "refresh"
}
}
```
## Testing
### Test Pattern
```javascript
const credential = await createCredential({
name: 'Test Credential',
type: 'httpBasicAuth',
data: { user: 'test', password: 'pass' }
});
assert(credential.id !== undefined);
assert(credential.name === 'Test Credential');
```
## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-12-26 | 1.0 | Story created for POST /credentials | Sarah (PO) |
