# Story 7.4: Credentials API Reference Documentation

**Epic:** Epic 7 - API Reference Documentation
**Story Points:** 4
**Priority:** Medium
**Status:** Ready for Implementation
**Estimated Page Count:** 8-10 pages

---

## User Story

**As a** developer managing workflow credentials
**I want** complete API reference for credential operations
**So that** I can understand security restrictions and implement schema-driven credential creation

---

## Story Description

### Current System

With Stories 7.1-7.3 completed:
- ✅ Architecture and workflows/executions APIs documented
- ❌ No credentials API reference
- ❌ n8n security restrictions not documented in API reference
- ❌ Schema-driven creation pattern not in API docs

### Enhancement

Create Credentials API reference documenting all 6 operations with emphasis on security model:
- **list_credentials** - Security restriction (blocked by n8n)
- **get_credential** - Security restriction (blocked by n8n)
- **create_credential** - Schema-driven creation
- **update_credential** - DELETE + CREATE pattern
- **delete_credential** - Permanent removal
- **get_credential_schema** - Schema retrieval for validation

---

## Acceptance Criteria

### AC1: Security Model Documentation

**Document:** `docs/api/credentials-api.md`

```markdown
# Credentials API Reference

Complete API reference for credential management (6 methods).

## Security Model

**n8n Credential Security (Epic 2):**

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

**Blocked Operations:**
- ❌ `list_credentials` - Returns security guidance
- ❌ `get_credential` - Returns security guidance

**Available Operations:**
- ✅ `create_credential` - Schema-driven creation
- ✅ `delete_credential` - Permanent removal
- ✅ `get_credential_schema` - Get field requirements
- ⚠️  `update_credential` - Use DELETE + CREATE pattern

**Recommended Approach:**
Manage credentials through n8n UI for visibility and control.

---

## get_credential_schema

Retrieve JSON schema for credential type to understand required fields.

### Purpose

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

### Request

**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:**
- `httpBasicAuth` - Basic HTTP authentication
- `httpHeaderAuth` - HTTP header authentication
- `oAuth2Api` - OAuth 2.0
- `googleSheetsOAuth2Api` - Google Sheets
- `slackApi` - Slack
- `gmailOAuth2` - Gmail
- `postgresDb` - PostgreSQL
- And 100+ more in n8n

---

### Response

\`\`\`typescript
interface CredentialSchema {
  type: 'object';
  properties: Array<{
    name: string;
    type: 'string' | 'number' | 'boolean' | 'options';
    required: boolean;
    displayName: string;
    description?: string;
    default?: any;
    options?: Array<{ name: string; value: any }>;
  }>;
}
\`\`\`

**Example - httpBasicAuth:**

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

---

## create_credential

Create new credential using schema-driven approach.

### Request

**Parameters:**

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

**TypeScript Interface:**

\`\`\`typescript
interface CreateCredentialParams {
  instance?: string;
  name: string;
  type: string;
  data: Record<string, any>;
  nodesAccess?: Array<{
    nodeType: string;
  }>;
}
\`\`\`

---

### Schema-Driven Creation Pattern

**Step 1: Get Schema**

\`\`\`typescript
const schema = await getCredentialSchema({
  type: 'httpBasicAuth',
  instance: 'production'
});
\`\`\`

**Step 2: Validate Data**

\`\`\`typescript
function validateCredentialData(
  data: any,
  schema: CredentialSchema
): void {
  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(', ')}`
    );
  }
}
\`\`\`

**Step 3: Create Credential**

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

console.log(`Created credential: ${credential.id}`);
\`\`\`

---

### Response

\`\`\`typescript
interface CreateCredentialResponse {
  id: string;
  name: string;
  type: string;
  createdAt: string;
  updatedAt: string;
  nodesAccess?: Array<{ nodeType: string }>;
}
\`\`\`

**Note:** `data` field NEVER returned (security)

---

## UPDATE Pattern (DELETE + CREATE)

Since n8n doesn't support direct credential updates:

\`\`\`typescript
async function updateCredential(
  credentialId: string,
  newData: CreateCredentialParams,
  instance?: string
): Promise<CreateCredentialResponse> {
  // Step 1: Delete old credential
  await deleteCredential({ id: credentialId, instance });

  // Step 2: Create new credential
  const newCredential = await createCredential({
    ...newData,
    instance
  });

  console.log(`Credential updated: ${credentialId} → ${newCredential.id}`);

  return newCredential;
}
\`\`\`

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

---

## Best Practices

### 1. Never Hardcode Credentials

\`\`\`typescript
// ❌ Bad: Hardcoded
const cred = await createCredential({
  data: { password: 'admin123' }
});

// ✅ Good: Environment variables
const cred = await createCredential({
  data: { password: process.env.API_PASSWORD }
});
\`\`\`

### 2. Always Use Schema Validation

\`\`\`typescript
// ✅ Good: Schema-driven
const schema = await getCredentialSchema({ type });
validateAgainstSchema(data, schema);
await createCredential({ type, data });

// ❌ Bad: Guessing fields
await createCredential({
  type: 'unknownType',
  data: { field1: 'value' }  // May be wrong!
});
\`\`\`

### 3. Manage Complex Credentials via UI

For OAuth2, JWT, and complex types:
- Use n8n UI for initial setup
- MCP server for simple types only
- Reference by ID in workflows

---

## Next Steps

- [Tags API Reference](./tags-api.md)
- [Security Best Practices](./security-best-practices.md)
```

---

## Dependencies

### Upstream Dependencies
- Story 7.1 (Architecture)
- Epic 2 (Credential Limitations)
- Epic 4 Story 4.4 (Credentials Tools)

---

## Definition of Done

- [ ] All 6 credential operations documented
- [ ] Security model explained
- [ ] Schema-driven pattern documented
- [ ] UPDATE pattern (DELETE + CREATE) explained
- [ ] Code examples provided

---

## Estimation Breakdown

**Story Points:** 4
**Page Count:** 8-10 pages
**Duration:** 2 days

---

**Status:** Ready for Implementation