# 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) |