DEV Community

realNameHidden
realNameHidden

Posted on

Your Proxy Should Only Allow Requests with a Custom Header — How Do You Do It in Apigee X?

#security #api #tutorial #cloud

Introduction

Imagine you’re running a private event. You don’t let just anyone walk in — you only allow people who show a special invite card at the entrance.

APIs work the same way.

In modern systems, APIs are constantly exposed to unknown clients, bots, and sometimes even malicious traffic. This is where Apigee shines. It acts like a smart security guard for your APIs.

In this blog, we’ll answer a very common real-world question:

“My proxy should only allow requests if a custom header is present. How do I enforce this?”

By the end of this post, you’ll learn:

  • Why header-based validation is important
  • How API proxies help enforce rules
  • A step-by-step Apigee X implementation
  • Best practices and common mistakes to avoid

Perfect for beginners and interview preparation 👍

Core Concepts

What Is an API Proxy in Apigee X?

Think of an API proxy as a security checkpoint between clients and your backend service.

Clients never talk directly to your backend. Instead, they go through the proxy, which can:

  • Validate requests
  • Enforce security rules
  • Block unwanted traffic
  • Log and monitor API usage

Why Check for a Custom Header?

A custom header is like a secret handshake.

Examples:

  • X-Client-Id
  • X-App-Name
  • X-Internal-Request

Real-World Analogy 🏢

Imagine entering an office:

  • Security asks for your ID card
  • No ID → No entry

Similarly:

  • Header present → Request allowed
  • Header missing → Request blocked 🚫

Use Cases & Benefits

✔ Restrict internal APIs

✔ Add an extra layer of API security

✔ Prevent unauthorized or accidental access

✔ Simple alternative to OAuth for basic use cases

Step-by-Step Guide: Allow Requests Only When a Custom Header Is Present

We’ll enforce this rule using policies in Apigee X.

Step 1: Decide the Header Name

Example header:

X-Request-Source
Enter fullscreen mode Exit fullscreen mode

Your rule:

Requests must contain X-Request-Source, otherwise reject them.

Step 2: Create a RaiseFault Policy

This policy will block requests if the header is missing.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault name="RF-Missing-Custom-Header">
    <FaultResponse>
        <Set>
            <StatusCode>400</StatusCode>
            <ReasonPhrase>Bad Request</ReasonPhrase>
            <Payload contentType="application/json">
                {
                  "error": "Missing required header: X-Request-Source"
                }
            </Payload>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>
Enter fullscreen mode Exit fullscreen mode

💡 This defines what response the client sees when the rule fails.

Step 3: Attach the Policy with a Condition

Attach this policy in the PreFlow → Request section of your proxy.

<Flow name="Validate-Custom-Header">
    <Condition>request.header.X-Request-Source = null</Condition>
    <Request>
        <Step>
            <Name>RF-Missing-Custom-Header</Name>
        </Step>
    </Request>
</Flow>
Enter fullscreen mode Exit fullscreen mode

📌 What this condition means:

  • If X-Request-Source does not exist
  • Trigger the RaiseFault policy
  • Stop request processing immediately

Step 4: Test Your API

❌ Request without header 

curl https://api.example.com/v1/data
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "error": "Missing required header: X-Request-Source"
}
Enter fullscreen mode Exit fullscreen mode

✅ Request with header 

curl -H "X-Request-Source: mobile-app" https://api.example.com/v1/data
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": "success"
}
Enter fullscreen mode Exit fullscreen mode

🎉 Your API is now protected!

Best Practices

✅ 1. Validate Early

Always validate headers in PreFlow so invalid requests are rejected fast.

✅ 2. Use Meaningful Error Messages

Clear error messages help consumers fix issues quickly.

✅ 3. Combine with Other Security

Header checks work best alongside:

  • OAuth
  • API Keys
  • Spike Arrest

✅ 4. Log Missing Headers

Use logging policies to monitor how often requests fail validation.

Common Mistakes to Avoid ❌

🚫 Checking headers in the response flow
🚫 Using case-sensitive header names incorrectly
🚫 Forgetting to handle null values
🚫 Relying only on headers for sensitive APIs

Conclusion

Custom header validation is one of the simplest and most effective security techniques in API Proxies in Apigee X.

Key Takeaways:

  • API proxies act as gatekeepers
  • Custom headers add lightweight security
  • RaiseFault + Conditions = clean enforcement
  • Easy to implement, powerful in practice

Start small, test often, and gradually layer more security as your APIs grow.

Call to Action 🚀

💬 Have you used custom headers in Apigee X before?
Drop your questions or experiences in the comments!

📌 Follow for more Apigee X, API security, and API traffic management tips.
🔔 Subscribe to stay updated with real-world API patterns and interview-ready scenarios.

Authoritative Links:

Top comments (0)