Advanced API Gateway Features: Authorizers and Domains

Previously in this course, we covered Implementing API Throttling: Managing Traffic in API Gateway to protect your backend from spikes. This lesson adds a layer of professional polish by securing access via custom logic, mapping your API to a branded domain, and structuring tiered service levels.

Beyond Basic Auth: The Lambda Authorizer

While API keys provide simple identification, they don't handle complex authentication logic. A Lambda Authorizer allows you to execute custom code before your main API logic runs. It takes a request header (like an Authorization token), validates it against a database or external identity provider, and returns an IAM policy that allows or denies the request.

How It Works

1. Client sends a request with an Authorization token.
2. API Gateway intercepts the request and invokes your Authorizer Lambda.
3. The Lambda evaluates the token and returns an IAM policy.
4. If the policy allows access, API Gateway proceeds to your backend; otherwise, it returns a 403 Forbidden.

Worked Example: Simple Token Validator

This function checks if a header contains a specific secret string.

JAVASCRIPT
exports.handler = async (event) => {
    const token = event.authorizationToken;
    
    // In production, verify JWTs or query a database here
    if (token === "super-secret-key") {
        return generatePolicy("user", "Allow", event.methodArn);
    }
    return generatePolicy("user", "Deny", event.methodArn);
};

function generatePolicy(principalId, effect, resource) {
    return {
        principalId,
        policyDocument: {
            Version: "2012-10-17",
            Statement: [{ Action: "execute-api:Invoke", Effect: effect, Resource: resource }]
        }
    };
}

Branding Your API with Custom Domains

By default, API Gateway provides a URL that looks like xyz.execute-api.region.amazonaws.com. For a professional web app, you want api.yourdomain.com.

To achieve this, you need three components:

1. ACM Certificate: A TLS/SSL certificate in the same region as your API.
2. Custom Domain Name: Registered in API Gateway, pointing to your ACM certificate.
3. Route 53 Record: A CNAME or A-record (Alias) pointing your domain to the API Gateway domain name provided by AWS.

Tiered Access via Usage Plans

We previously touched on Implementing API Throttling: Managing Traffic in API Gateway, but usage plans take this further by grouping API keys into tiers (e.g., "Free", "Premium").

Hands-on Exercise: Implement a Basic Authorizer

1. Create a new Lambda function named MyAuthorizer.
2. Paste the provided validation code above.
3. In your API Gateway console, navigate to "Authorizers" and create a new "Lambda Authorizer".
4. Select your function and set the "Token Source" header to Authorization.
5. Attach this authorizer to one of your existing API methods and test it using the "Test" button with the header Authorization: super-secret-key.

Common Pitfalls

• Caching Authorizer Results: API Gateway caches authorizer results by default (TTL is 300 seconds). If you revoke a user's access, they might still be able to hit your API until the cache expires. Adjust the TTL to 0 if you need immediate revocation.
• Missing Intermediate Certificates: When using custom domains, ensure your ACM certificate chain is complete. If you're using a custom domain with CloudFront, remember that updates to the domain mapping can take several minutes to propagate.
• Over-Throttling: Don't set usage plan limits too low during development; you might block your own testing scripts. Always test your limits in a staging environment first.

FAQ

Can I use multiple authorizers on one API? Yes, you can assign different authorizers to different routes within the same API Gateway.

Does a Custom Domain cost extra? API Gateway charges for each custom domain name association per hour, plus standard request pricing.

Can I use a Lambda Authorizer for non-JWT tokens? Absolutely. Because it's just code, you can validate anything—from OAuth flows to simple static headers or even IP address allow-lists.

Recap

We’ve now covered how to secure your API with custom logic, brand your endpoints, and manage user access tiers. Using the techniques from this lesson, you can transform your project into a production-ready service. As you continue your Full-Stack API Integration: Connecting Frontend to Backend, these security and routing layers ensure your data remains protected.

Up next

Database Migrations and DynamoDB Streams: Learning to react to data changes in real-time.