Professional authentication system for securing API documentation with dual authentication support, enterprise-grade security, and seamless user experience.
{
"authentication": {
"enabled": true,
"type": "local",
"users": [
{
"username": "admin",
"password": "admin123",
"role": "admin"
}
]
}
}
# Generate protected documentation
apidoc -i src/ -o docs/
# Access at: http://localhost:8080
# Login: admin / admin123
Perfect for teams and internal documentation.
{
"authentication": {
"type": "local",
"users": [
{
"username": "developer",
"password": "dev2024!",
"role": "developer",
"name": "John Developer",
"email": "john@company.com",
"permissions": ["read", "write"]
},
{
"username": "manager",
"password": "mgr2024!",
"role": "manager",
"name": "Jane Manager",
"email": "jane@company.com",
"permissions": ["read", "admin"]
}
]
}
}
Enterprise integration with existing systems.
{
"authentication": {
"type": "remote",
"endpoint": "https://auth.company.com/api/validate",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json"
},
"timeout": 5000,
"retries": 3
}
}
{
"authentication": {
"enabled": true,
"type": "local",
"users": [
{
"username": "frontend",
"password": "fe2024!",
"role": "frontend",
"permissions": ["read", "examples"]
},
{
"username": "backend",
"password": "be2024!",
"role": "backend",
"permissions": ["read", "write", "admin"]
},
{
"username": "qa",
"password": "qa2024!",
"role": "qa",
"permissions": ["read", "test"]
}
],
"roleConfig": {
"frontend": {
"landingPage": "/examples",
"theme": "developer"
},
"backend": {
"landingPage": "/technical",
"theme": "technical"
},
"qa": {
"landingPage": "/testing",
"theme": "testing"
}
}
}
}
{
"authentication": {
"enabled": true,
"type": "remote",
"endpoint": "https://sso.enterprise.com/api/auth",
"headers": {
"Authorization": "Bearer ${ENTERPRISE_TOKEN}",
"X-Client-ID": "apidoc-portal"
},
"security": {
"requireHttps": true,
"maxAttempts": 3,
"lockoutDuration": 1800,
"csrfProtection": true
},
"audit": {
"enabled": true,
"logFile": "/var/log/apidoc-auth.log",
"includeIP": true,
"includeUserAgent": true
}
}
}
{
"authentication": {
"enabled": true,
"type": "local",
"loginPage": {
"title": "Developer Portal",
"subtitle": "Access your API documentation",
"logo": "./assets/client-logo.png",
"primaryColor": "#007bff",
"customCSS": "./assets/client-theme.css"
},
"users": [
{
"username": "client1",
"password": "secure123!",
"role": "client",
"name": "Client Company",
"permissions": ["read"],
"metadata": {
"company": "Client Corp",
"tier": "premium"
}
}
]
}
}
{
"authentication": {
"enabled": true,
"type": "local|remote",
"debug": false,
"verbose": true
}
}
{
"authentication": {
"session": {
"secret": "your-session-secret-key",
"timeout": 3600,
"secure": true,
"httpOnly": true,
"sameSite": "strict",
"rememberMe": true,
"maxAge": 2592000
}
}
}
{
"authentication": {
"security": {
"maxAttempts": 5,
"lockoutDuration": 900,
"requireHttps": true,
"csrfProtection": true,
"sessionRegeneration": true,
"passwordStrength": {
"enabled": true,
"minLength": 8,
"requireUppercase": true,
"requireLowercase": true,
"requireNumbers": true,
"requireSymbols": false
}
}
}
}
{
"authentication": {
"loginPage": {
"title": "Your API Portal",
"subtitle": "Secure documentation access",
"logo": "./assets/logo.png",
"favicon": "./assets/favicon.ico",
"primaryColor": "#007bff",
"secondaryColor": "#6c757d",
"backgroundColor": "#f8f9fa",
"backgroundImage": "./assets/background.jpg",
"customCSS": "./assets/custom-login.css",
"languages": {
"en": { "title": "API Documentation" },
"es": { "title": "Documentación API" },
"fr": { "title": "Documentation API" }
},
"defaultLanguage": "en"
}
}
}
# Install APIDoc with authentication
npm install -g @hrefcl/apidoc
# Generate protected documentation
apidoc -i src/ -o docs/ --auth
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm install -g @hrefcl/apidoc && \
apidoc -i src/ -o docs/
EXPOSE 3000
CMD ["npx", "http-server", "docs", "-p", "3000"]
# Build and run
docker build -t my-api-docs .
docker run -p 3000:3000 my-api-docs
version: '3.8'
services:
api-docs:
build: .
ports:
- "3000:3000"
environment:
- AUTH_TYPE=remote
- AUTH_ENDPOINT=https://auth.company.com/api/validate
- SESSION_SECRET=${SESSION_SECRET}
volumes:
- ./docs:/app/docs
restart: unless-stopped
# .env.development
NODE_ENV=development
AUTH_ENABLED=true
AUTH_TYPE=local
SESSION_SECRET=dev-secret-key
SESSION_TIMEOUT=28800
MAX_LOGIN_ATTEMPTS=10
REQUIRE_HTTPS=false
# .env.staging
NODE_ENV=staging
AUTH_ENABLED=true
AUTH_TYPE=remote
AUTH_ENDPOINT=https://staging-auth.company.com/api/validate
SESSION_SECRET=staging-secret-key
SESSION_TIMEOUT=7200
MAX_LOGIN_ATTEMPTS=5
REQUIRE_HTTPS=true
# .env.production
NODE_ENV=production
AUTH_ENABLED=true
AUTH_TYPE=remote
AUTH_ENDPOINT=https://auth.company.com/api/validate
SESSION_SECRET=super-secure-production-secret
SESSION_TIMEOUT=3600
MAX_LOGIN_ATTEMPTS=3
REQUIRE_HTTPS=true
AUDIT_ENABLED=true
{
"authentication": {
"audit": {
"enabled": true,
"logFile": "./logs/auth.log",
"logLevel": "info",
"includeIP": true,
"includeUserAgent": true,
"logSuccessfulLogins": true,
"logFailedAttempts": true,
"logLogouts": true,
"logSessionExpiry": true
}
}
}
// Example log analysis
{
"timestamp": "2024-01-15T14:30:00Z",
"event": "login_success",
"username": "developer",
"ip": "192.168.1.100",
"userAgent": "Mozilla/5.0...",
"sessionId": "abc123...",
"duration": 145
}
// test/auth.test.js
const { AuthSystem } = require('@hrefcl/apidoc');
describe('Authentication System', () => {
test('should authenticate valid user', async () => {
const auth = new AuthSystem({
type: 'local',
users: [{ username: 'test', password: 'test123' }]
});
const result = await auth.authenticate('test', 'test123');
expect(result.success).toBe(true);
});
test('should reject invalid credentials', async () => {
const auth = new AuthSystem({
type: 'local',
users: [{ username: 'test', password: 'test123' }]
});
const result = await auth.authenticate('test', 'wrong');
expect(result.success).toBe(false);
});
});
# Test authentication endpoints
curl -X POST http://localhost:3000/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"test","password":"test123"}'
# Test protected endpoint
curl -H "Cookie: session=..." \
http://localhost:3000/docs/
# Check configuration
apidoc --validate-config
# Debug mode
AUTH_DEBUG=true apidoc -i src/ -o docs/
{
"authentication": {
"session": {
"secret": "change-this-secret",
"secure": false,
"sameSite": "lax"
}
}
}
{
"authentication": {
"security": {
"requireHttps": false
}
}
}
APIDoc Authentication System is part of APIDoc 4.0 and is licensed under the MIT License.
Start securing your API documentation today with professional authentication that your team and clients will love!