# Story 2.6.1: Implement GET /credentials (List)
<!-- Powered by BMAD™ Core -->
## Status
**✅ COMPLETED** - December 26, 2024
**Solution:** Returns informative guidance message instead of API error
**Implementation Status:**
- ✅ Code implementation complete
- ✅ MCP tool registered and enabled
- ✅ Returns helpful guidance when called
- ✅ Provides alternative access methods
- ✅ No errors - graceful handling
**API Limitation:** n8n API does not support GET /credentials (tested v1.82.3, v2.1.4)
**User Experience:** Tool provides clear guidance and security explanation
**Details:** See `docs/STORY-2.6.1-API-LIMITATION-DISCOVERY.md`
## Story
**As a** workflow automation user,
**I want** to list all credentials configured in my n8n instance through the MCP server,
**so that** I can view, manage, and understand which credentials are available for workflow integrations without accessing the n8n UI.
## Acceptance Criteria
1. New `list_credentials` MCP tool registered and functional
2. Tool supports pagination (cursor-based) for large credential lists
3. Security: Sensitive credential data is NOT returned (only metadata)
4. Response includes: id, name, type, nodesAccess, timestamps
5. Multi-instance routing works correctly
6. Error handling for unauthorized access (401)
7. Comprehensive testing with various credential types
8. Documentation updated with security notes
9. Integration with test infrastructure
10. Credential metadata validation complete
## Tasks / Subtasks
### Task 1: Study Credentials API Documentation (AC: 3, 4)
- [ ] Read docs/n8n-api-docs/30-CREDENTIALS-API.md Lines 35-180
- [ ] Understand security model (no sensitive data in list)
- [ ] Document credential structure and nodesAccess field
- [ ] Note credential types and metadata fields
- [ ] Identify security considerations
### Task 2: Implement listCredentials in N8NApiWrapper (AC: 1, 2, 5)
- [ ] Add `listCredentials` method to src/services/n8nApiWrapper.ts
- [ ] Use callWithInstance pattern for multi-instance support
- [ ] Support pagination parameters (limit, cursor)
- [ ] Add error handling and logging
- [ ] Follow existing API wrapper patterns
### Task 3: Register list_credentials MCP Tool (AC: 1)
- [ ] Add tool definition to src/index.ts
- [ ] Define input schema with pagination params
- [ ] Include instance parameter
- [ ] Add comprehensive description with security notes
- [ ] Implement request handler
- [ ] Map to N8NApiWrapper.listCredentials
### Task 4: Security Implementation (AC: 3, 4)
- [ ] Verify sensitive data NOT returned by API
- [ ] Document security behavior clearly
- [ ] Test that credential `data` field is absent
- [ ] Add security warnings in tool description
- [ ] Document credential access control
### Task 5: Create Comprehensive Tests (AC: 7)
- [ ] **Test 5.1**: List all credentials
- [ ] Verify response structure
- [ ] Check metadata fields present
- [ ] Confirm sensitive data absent
- [ ] **Test 5.2**: Test pagination
- [ ] Test limit parameter
- [ ] Test cursor-based pagination
- [ ] Verify nextCursor handling
- [ ] **Test 5.3**: Test with multiple credential types
- [ ] Create credentials of different types
- [ ] Verify all types listed correctly
- [ ] Check type field values
- [ ] **Test 5.4**: Test nodesAccess field
- [ ] Verify nodesAccess array structure
- [ ] Check nodeType and date fields
- [ ] **Test 5.5**: Multi-instance routing
- [ ] List from default instance
- [ ] List from specific instance
- [ ] Verify instance isolation
- [ ] **Test 5.6**: Error scenarios
- [ ] Test with invalid API key (401)
- [ ] Test with invalid pagination params
- [ ] Verify error responses
- [ ] **Test 5.7**: Empty credential list
- [ ] Test when no credentials exist
- [ ] Verify empty array returned
### Task 6: Update Documentation (AC: 8)
- [ ] Update README.md with list_credentials example
- [ ] Add security notes about sensitive data
- [ ] Update CLAUDE.md with implementation notes
- [ ] Document credential types and structure
- [ ] Add pagination examples
- [ ] Update CHANGELOG.md
### Task 7: Integration (AC: 9)
- [ ] Add tests to test-mcp-tools.js
- [ ] Create credential test fixtures
- [ ] Add cleanup utilities
- [ ] Document test procedure
## Dev Notes
### Credential Structure (Metadata Only)
```typescript
{
id: string; // Credential ID
name: string; // User-defined name
type: string; // Credential type (e.g., 'googleDriveOAuth2Api')
nodesAccess: Array<{ // Which nodes use this credential
nodeType: string; // e.g., 'n8n-nodes-base.googleDrive'
date: string; // ISO 8601 last access date
}>;
createdAt: string; // ISO 8601
updatedAt: string; // ISO 8601
}
```
**Security:** `data` field (containing secrets) is NEVER returned in list
### MCP Tool Schema
```typescript
{
name: 'list_credentials',
description: 'List all credentials (metadata only, sensitive data excluded for security)',
inputSchema: {
type: 'object',
properties: {
limit: {
type: 'number',
description: 'Max results (default: 100)'
},
cursor: {
type: 'string',
description: 'Pagination cursor'
},
instance: {
type: 'string',
description: 'Instance identifier (optional)'
}
}
}
}
```
### Common Credential Types
- `googleDriveOAuth2Api` - Google Drive OAuth2
- `slackApi` - Slack
- `githubApi` - GitHub
- `httpBasicAuth` - HTTP Basic Auth
- `httpHeaderAuth` - HTTP Header Auth
- And 100+ more types in n8n
## Testing
### Test Approach
1. Create test credentials of various types
2. List and verify metadata structure
3. Confirm security (no sensitive data)
4. Test pagination
5. Test multi-instance isolation
## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-12-26 | 1.0 | Story created for GET /credentials implementation | Sarah (PO) |
