🔒 OWASP API Security Training

📚 Introduction to API Documentation

API documentation serves as the blueprint for interacting with Application Programming Interfaces. However, security professionals must understand that documentation should be treated with caution. Since developers create this documentation, it may contain vulnerabilities, inconsistencies, or intentional obfuscation that can impact security testing.

✅ Components of Good API Documentation

Essential Elements:

🛠️ Major API Documentation Tools & Formats

1. OpenAPI Specification (Swagger)

2. Postman Collections

{
  "variable": [
    {
      "key": "api_key",
      "value": "sk_live_51Hxxx...",  ← EXPOSED SECRET
      "type": "string"
    },
    {
      "key": "admin_token",
      "value": "Bearer eyJhbGc...",  ← EXPOSED TOKEN
      "type": "string"
    }
  ]
}

3. API Blueprint

🔐 Authentication & Authorization Documentation

Why Clear Authentication Documentation Matters:

Different APIs require different authentication mechanisms. Proper documentation should clearly specify how to authenticate, but this is often poorly documented or completely missing.

Testing Authentication Commands:

📊 API Versioning & Documentation

Understanding Version Management:

APIs often maintain multiple versions simultaneously. Each version may have its own documentation, security controls, and vulnerabilities. Older versions frequently contain security flaws that have been patched in newer versions.

Version Discovery Commands:

🧪 Interactive Documentation & Testing

Benefits of Interactive Documentation:

• Web Interface Testing: Try endpoints directly through Swagger UI or similar tools
• Quick Prototyping: Understand API behavior without writing code
• curl Command Generation: Convert interactive requests to curl commands
• Code Snippet Export: Generate Python, JavaScript, or other language examples

Converting Swagger to curl Commands:

Converting curl to Python Script:

import requests

url = "https://api.example.com/v1/users"
headers = {
    "accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN"
}
data = {
    "username": "testuser",
    "email": "[email protected]"
}

response = requests.post(url, headers=headers, json=data)
print(f"Status Code: {response.status_code}")
print(f"Response: {response.json()}")

🎯 Beyond Documentation: Discovery Techniques

Endpoint Discovery:

Documentation rarely covers all endpoints. Use these techniques to discover hidden or undocumented endpoints:

Parameter Discovery:

Common Hidden Parameters to Test:

⚠️ Common Pitfalls in API Documentation

🛡️ The Role of Documentation in Security

Security Best Practices for Documentation:

Common Documentation Exposure Points:

🔍 Practical Security Testing Workflow

📝 Key Takeaways

🎓 Summary

API documentation is a double-edged sword in security testing. While it provides valuable information about API structure and functionality, it should never be your sole source of truth. The most critical vulnerabilities often exist in undocumented endpoints, forgotten API versions, or poorly secured documentation endpoints themselves.

Remember: Developers prioritize functionality over security, and documentation practices reflect this reality. Your job as a security professional is to find what's hidden, test what's assumed to be secure, and never trust that documentation tells the complete story.