Create API proxies to IAM-protected services

This topic provides high-level guidance on building API proxies to call AWS services protected by AWS Identity and Access Management (IAM). The following diagram illustrates the message flow using AWS Lambda as an example. The same flow applies to any IAM-protected service.

Upload the AWS user keys to an encrypted KVM

While Edge provides multiple data persistence options, the most secure place to store your AWS Access Key and Secret Access Key is an Edge encrypted key value map (KVM).

After creating and downloading the keys for your AWS user, as described in Getting started with AWS integration, add the keys to an Edge encrypted KVM, as described in Working with key value maps.

The next section provides information about retrieving the keys to send in your API calls to AWS.

Build the API proxy

Create an API proxy to retrieve the AWS keys from your Edge encrypted KVM and construct a request to AWS. Since you may want to leverage AWS Node.js functions, as well as Edge functions to retrieve encrypted keys, you can create a Node.js API proxy.

See the relevant AWS documentation for information on what to include in calls to specific AWS services. For example, some AWS services require specific HTTP headers.

See the following topics for a Node.js-in-Edge overview, instructions on creating a new Node.js proxy or adding Node.js to an existing proxy, and links to samples.

Quick overview

Here's a quick conceptual overview. API proxies often route requests directly to a backend service (for example,, as shown in the following sample API proxy TargetEndpoint configuration:

<TargetEndpoint name="default">

However, if you're using Node.js to make calls to a backend, your API proxy hands control off to a Node.js target, shown here:

<TargetEndpoint name="default">

You build that Node.js target and its associated resources to get the AWS keys, construct the request, and route it to the appropriate AWS service.

Even though you're using Node.js to make the final request to AWS, you can still attach any desired policies to your API proxy for security, mediation, transformation, and so on.

Retrieving AWS keys from an encrypted KVM

Edge provides an apigee-access Node.js module that lets you retrieve the AWS Access Key and Secret Access Key from an Edge encrypted KVM at runtime. You can then include those keys in your requests to AWS.

Proxying AWS Lambda

You can invoke AWS Lambda functions from Edge API proxies over HTTPS. Build an Edge API proxy that uses Node.js to retrieve the AWS user Acccess Key and Secret Access Key and build the request to Lambda. Node.js is useful between Edge and Lambda in other ways as well, since orchestration between the API proxy, Lambda, and other AWS services requires granular coding flexibility that Node.js provides.

In your Node.js code, map individual methods, such as GET and PUT, to specific Lambda functions. Then, when a user sends a request through your API proxy, Edge invokes the corresponding Lambda function. (In Lambda terms, the API proxy is a push event model to Lambda.)

Integration guidelines

  • On your Lambda functions, set the proper execution role and permissions. See the following topics for more information:
  • See the Edge Node.js links above for detailed information on using Node.js in Edge to call backend services.
  • In your API proxy, prior to the request being forwarded to AWS, you can use Edge policies for inbound security, message mediation, transformation, and so on.
  • Edge can invoke Lambda functions and get a responses back in real time by specifying RequestResponse as the invocation type. For information about invocation types, see
  • Map REST error codes in your API proxies. For example, if a Lambda function throws an error, the HTTP status code from Lambda will still be 200, but the payload returned will be an error. Parse the response payload with JavaScript or Node.js in the API proxy and rebuild an appropriate error to return to the client.
    This blog post also has best-practices guidance on handling response errors.

Proxying Amazon S3

Use Amazon S3 in place of FTP or other traditional forms of batch file upload and download. To ensure the successful transfer of large files (10MB maximum in Edge Public Cloud, 3MB in Edge for Private Cloud), you can enable request/response streaming in your API proxy. See the following topics:

Streaming is not supported in Node.js on Edge. So if you have streaming enabled on Edge, Edge acts as a passthrough, and you won't be able to use Node.js to retrieve the AWS user keys from the Edge secure store to pass to S3. In that case, you'll need to secure S3 in a way that doesn't require user keys. For more information, see

Messages larger than supported sizes

If message size exceeds the Edge limit (10MB for Edge Public Cloud and 3MB for Private Cloud), you have a couple of options:

  • Use Edge to bypass Edge: Use a Node.js-enabled API proxy to check for message size. If the size exceeds the limit, use the AWS Node.js SDK to generate a temporary URL to post directly to S3, then redirect the large-payload request there.
  • Private Cloud: In Edge for Private Cloud, you can change the default 3MB message size limit. For more information, see the Edge Best Practices topic.

Proxying an AWS relational database

Apigee provides connectors to expose relational databases as APIs. You can use the “SQL volos connectors” as a starting point if you need to expose your AWS relational database as a REST API. For more information, see volos-connectors GitHub repository.

TLS/SSL-protected services

If the AWS service you want to proxy is protected by TLS/SSL rather than IAM, see Create API proxies to TLS/SSL-protected services.

See also