# Story 2.6.5: Implement DELETE /credentials/{id}

<!-- Powered by BMAD™ Core -->

## Status
**Draft**

## Story

**As a** workflow automation user,
**I want** to delete unused credentials from my n8n instance through the MCP server,
**so that** I can maintain security hygiene by removing obsolete authentication data and prevent credential sprawl.

## Acceptance Criteria

1. New `delete_credential` MCP tool registered and functional
2. Tool deletes credential by ID
3. Safety check: Warn/block deletion if credential is in use by workflows
4. Multi-instance routing works correctly
5. Error handling for non-existent credentials (404)
6. Error handling for credentials in use (409 or warning)
7. Deletion is permanent (not soft delete)
8. Comprehensive testing including in-use scenarios
9. Documentation with safety warnings
10. Cascade behavior documented and tested

## Tasks / Subtasks

### Task 1: Implement deleteCredential (AC: 1, 2, 4)
- [ ] Add `deleteCredential` method to N8NApiWrapper
- [ ] Use callWithInstance pattern
- [ ] Use DELETE method
- [ ] Support credentialId parameter
- [ ] Add error handling

### Task 2: Register delete_credential Tool (AC: 1)
- [ ] Add tool definition to src/index.ts
- [ ] Define input schema with credentialId
- [ ] Include instance parameter
- [ ] Add safety warnings in description
- [ ] Implement request handler

### Task 3: Safety Logic (AC: 3, 6)
- [ ] Research n8n deletion behavior
- [ ] Document in-use credential handling
- [ ] Test deletion of active credentials
- [ ] Verify error responses
- [ ] Add safety documentation

### Task 4: Create Tests (AC: 8)
- [ ] **Test 4.1**: Delete unused credential
  - [ ] Create credential
  - [ ] Delete immediately
  - [ ] Verify removed from list
  - [ ] Confirm 404 on retrieval
- [ ] **Test 4.2**: Delete credential in use (AC: 3, 6)
  - [ ] Create credential
  - [ ] Assign to workflow
  - [ ] Attempt deletion
  - [ ] Verify behavior (blocked or cascaded)
  - [ ] Document actual behavior
- [ ] **Test 4.3**: Deletion permanence (AC: 7)
  - [ ] Delete credential
  - [ ] Verify truly removed
  - [ ] Check no soft delete
  - [ ] Confirm unrecoverable
- [ ] **Test 4.4**: Workflow impact
  - [ ] Delete credential used by workflow
  - [ ] Check workflow behavior
  - [ ] Verify workflow still exists
  - [ ] Document credential removal impact
- [ ] **Test 4.5**: Multi-instance deletion
  - [ ] Delete from default instance
  - [ ] Delete from specific instance
  - [ ] Test cross-instance (404)
- [ ] **Test 4.6**: Error scenarios
  - [ ] Delete non-existent credential (404)
  - [ ] Delete already deleted credential
  - [ ] Invalid credential ID
- [ ] **Test 4.7**: Cascade behavior (AC: 10)
  - [ ] Document what happens to workflows
  - [ ] Test node credential references
  - [ ] Verify cascade semantics

### Task 5: Documentation (AC: 9, 10)
- [ ] Add deletion examples
- [ ] Document safety considerations
- [ ] Explain cascade behavior
- [ ] Add warnings about in-use credentials
- [ ] Update README and CHANGELOG

### Task 6: Integration
- [ ] Add to test suite
- [ ] Safety check tests
- [ ] Cleanup utilities

## Dev Notes

### Deletion Safety

**Question:** What happens when deleting credential in use?

**Possible Behaviors:**
1. **Blocked (409 Conflict):** "Credential is in use by X workflows"
2. **Allowed with Warning:** Credential deleted, workflows keep reference
3. **Cascade:** Credential deleted, removed from all workflows

**Testing Required:** Determine actual n8n behavior

### MCP Tool Schema
```typescript
{
  name: 'delete_credential',
  description: 'Delete a credential (WARNING: Check if in use first)',
  inputSchema: {
    type: 'object',
    properties: {
      credentialId: {
        type: 'string',
        description: 'ID of credential to delete'
      },
      instance: {
        type: 'string',
        description: 'Instance identifier (optional)'
      }
    },
    required: ['credentialId']
  }
}
```

### Safety Check Strategy

**Option 1:** Pre-delete check
```javascript
async function deleteCredential(id) {
  // Check usage first
  const credential = await getCredential(id);
  if (credential.nodesAccess.length > 0) {
    throw new Error('Credential in use by workflows');
  }
  // Proceed with deletion
  await api.delete(`/credentials/${id}`);
}
```

**Option 2:** Let n8n enforce
```javascript
async function deleteCredential(id) {
  // Let n8n API handle safety checks
  // Return appropriate error if blocked
  await api.delete(`/credentials/${id}`);
}
```

**Decision:** Test n8n behavior first, then implement appropriate strategy

## Testing

### Test Pattern
```javascript
// Test deletion of unused credential
const cred = await createCredential({...});
await deleteCredential(cred.id);
const list = await listCredentials();
assert(!list.data.find(c => c.id === cred.id));

// Test deletion of in-use credential
const workflow = await createWorkflow({
  // ... uses credential
});
try {
  await deleteCredential(cred.id);
  // Document if allowed or blocked
} catch (error) {
  // Document error response
}
```

## Change Log

| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-12-26 | 1.0 | Story created for DELETE /credentials/{id} | Sarah (PO) |