Skip to main content

Onboard an API with Amazon API Gateway


Prerequisites​

The APIsec platform allows onboarding via the AWS gateway using three credential types.

  1. AWS User
  2. Assume Role
  3. Central Role ARN

Prerequisites for AWS User​

1. Create an IAM user​

  1. Log in to your AWS Management Console.
  2. Navigate to IAM → Users → Create Users.

IAM Users page in the AWS console

  1. Enter a Username (e.g., apisec-apigateway-user)

Enter a username

  1. Click Next

Next button

  1. Click Create User

Create User button


2. Attach required permissions​

  1. Click the user created in the previous step.

Select the IAM user

  1. In the Permissions tab, select Create in-line policy from the Add Permissions dropdown.

Create in-line policy option

  1. Add the following custom inline policy in JSON format.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "apigateway:GET",
"Resource": "*"
}
]
}

Inline policy JSON editor

  1. Click Next

Next button

  1. Enter policy name and click Create policy

Policy name and Create policy button


3. Create access key​

  1. Once the IAM user is created, go to the user's Security credentials tab.

Security credentials tab

  1. Under Access keys, click Create access key.

Create access key button Create access key options

  1. Copy the Access Key ID and Secret Access Key to integrate AWS API Gateway in the APIsec platform.

Access Key ID and Secret Access Key


Prerequisites for Assume Role​

APIsec supports integrating with AWS API Gateway using IAM Roles, offering a more secure and manageable alternative to long-lived IAM User credentials.

With this enhancement, you can configure a self-owned IAM role in your account for APIsec to use — eliminating the need to store static access keys. APIsec utilizes the AWS Security Token Service (STS) to temporarily assume the specified role, obtaining short-lived credentials to securely perform the required read operations (e.g., retrieving API definitions from API Gateway).

This approach aligns with AWS security best practices by:

  • Reducing the exposure of long-lived IAM credentials.
  • Enabling fine-grained access control via trust policies.
  • Providing an auditable and controlled mechanism for APIsec to access AWS resources.

Once configured, APIsec securely assumes your IAM Role at runtime to perform necessary operations on API Gateway, ensuring a secure, auditable, and compliant integration flow.

Assume Role integration overview

For the APIsec platform to onboard via Assume Role, it needs a Role Arn (Amazon Resource Name of the IAM role to assume for this connection) and a Session Name (to identify the temporary security credentials used in this connection), which is optional.

1. Contact APIsec Support​

Before proceeding, contact APIsec Support to obtain:

  • The AWS ARN that includes APIsec's AWS Account ID.

    This ARN is required when configuring the trust policy in your AWS account.

Example

arn:aws:iam::111122223333:role/MyAccessRole

2. Create an IAM role in your AWS account​

  • Sign in to your AWS Management Console.

  • Navigate to IAM → Roles → Create role. Create role in IAM

  • Select Trusted Entity Type → Another AWS account.

  • Enter the other AWS Account ID. Select the trusted entity type

3. Attach a policy to grant GET access to the API Gateway​

Attach a new or existing policy that provides read-only (GET) permissions to the API Gateway. Example Policy

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["apigateway:GET"],
"Resource": "*"
}
]
}

Save this as APIGatewayGETAccessPolicy and attach it to the IAM Role. API Gateway GET access policy

4. Configure the trust policy​

Once the IAM Role is created, define a "Trust Relationship" allowing APIsec's AWS Account to assume it. Below is the sample example. Replace the ARN which you have got from the APIsec support team in the first step.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyAccessRole"
},
"Action": "sts:AssumeRole"
}
]
}

Trust policy JSON

You can edit this policy under: IAM → Roles → [Your Role] → Trust relationships → Edit trust policy.

5. Copy the Role ARN​

Once your IAM Role is ready:

    1. Go to the Role Summary page in AWS IAM.
    1. Copy the Role ARN (e.g., arn:aws:iam::999988887777:role/APIGatewayAccessRole).

Role ARN on the role summary page


Prerequisites for Central Role ARN​

Organizations managing APIs across multiple AWS accounts often maintain separate integration connections in the APIsec platform using individual Assume Role configurations. This approach introduces scalability issues and operational complexity as the number of AWS accounts increases.

To streamline integration management, a Cross-Account IAM Role Assumption model can be implemented. In this model, a Central IAM Role in the primary AWS account is granted permissions to assume Child Roles across multiple linked accounts. Each Child Role provides controlled access to resources such as API Gateway within its respective account.

The APIsec platform connects to the Central Role, which assumes the necessary Child Roles to access and onboard APIs across all accounts. This enables organizations to:

  • Create and manage one AWS integration connection in the APIsec platform.
  • Access and onboard APIs from multiple AWS accounts through delegated role assumption.
  • Creating IAM roles in child accounts is managed from the central account, allowing the solution to scale without requiring manual setup.
  • Minimize operational overhead in large multi-account environments.

Central Role ARN architecture

Before deploying CloudFormationStack for CentralRole and StackSets for ChildRole, ensure the following prerequisites are met:

  • AWS Organizations is enabled, and your account is the management account.
  • You've enabled trusted access for AWS CloudFormation StackSets in Organizations.
  • You have the necessary IAM permissions to create StackSets and IAM roles.
  • You've identified the central account and the target child accounts or Organizational Units (OUs).

1. Central Role stack (in central account)​

This CloudFormation template creates a CentralRole that can assume roles in child accounts and list accounts via AWS Organizations.

AWSTemplateFormatVersion: "2010-09-09"

Resources:
APIsecCentralRole:
Type: AWS::IAM::Role
Properties:
RoleName: APIsecCentralRole
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Principal:
AWS: arn:aws:iam::<EXTERNAL_USER_OR_ACCOUNT>:role/APIsecExternalRole
Action: sts:AssumeRole
Policies:
- PolicyName: APIsecCentralRolePolicy
PolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Action:
- sts:AssumeRole
- organizations:ListAccounts
Resource: "*"
note

Contact the APIsec support team to get the APIsec AWS ARN to update in the above template before deployment.

2. Deploy the Central Role stack via the console​

To deploy the CentralRole CloudFormation stack from a local template file, follow these steps:

  1. Go to the AWS Management Console and open the CloudFormation service.

AWS Management Console

  1. Click Create stack
    • For Prepare template, select Choose existing template.
    • Under Specify template, select Upload a template file.
    • Click Choose file, and upload your central-role.yaml (the CloudFormation file containing APIsecCentralRole).
    • Click Next to proceed with stack configuration.

Create stack

  1. Enter a stack name, for example: CentralRoleStack.

CentralRoleStack

  1. Leave the parameters as default and click Next.

  2. On the Configure stack options page, you can leave all settings as default or optionally add tags for easier identification.

    Scroll down to the bottom of the page and select the checkbox:

    "I acknowledge that AWS CloudFormation might create IAM resources."

    Click Next.

Configure Stack Options

CRA Additional Settings

  1. On the Review and Create page, review the configuration details, then scroll down and click Submit to create the stack.

CRA Review and Create

CRA Configure Stack Options

CRA Rollback Configuration

  1. Wait a few minutes for the deployment to complete.

  2. The stack status should change to CREATE_COMPLETE once it's successfully created.

CRA CREATE_COMPLETE

  1. Go to AWS IAM and open Roles to copy the APIsecCentralRole ARN.

  2. Use this ARN in the APIsec platform after deploying the ChildRole StackSets (if not already done).

3. Child Role StackSet template (target accounts)​

This template should be deployed via an Organization-level StackSet to all target accounts or OUs where the CentralRole needs to access the API Gateway.

AWSTemplateFormatVersion: "2010-09-09"

Resources:
APIsecChildRole:
Type: AWS::IAM::Role
Properties:
RoleName: APIsecChildRole
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Principal:
AWS: "arn:aws:iam::<CENTRAL_ACCOUNT_ID>:role/APIsecCentralRole"
Action: sts:AssumeRole
Policies:
- PolicyName: APIsecChildRolePolicy
PolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Action:
- apigateway:GET
Resource: "*"
note

Update CENTRAL_ACCOUNT_ID with your AWS org root management account ID in the above template before deployment.

4. StackSet deployment steps (console)​

  1. In the AWS CloudFormation console under StackSets (within your management account), choose Create StackSet to begin the setup.

CRA Delegated Admins

  1. Choose a template
    a) Under Permissions, select Service-managed permissions.
    b) Under Prerequisite – Prepare template, select Template is ready.
    c) Under Specify template, choose Upload a template file and upload the ChildRole template file.
    d) Click Next to continue.

CRA ChildRole

  1. On the Specify Stack Details page, enter a StackSet name (e.g., ChildRoleStackSet) and click Next.

CRA Specify Stack

  1. Under Execution configuration, select Inactive to ensure stack instances are created one after another. In the Capabilities section, check the box for:

    I acknowledge that AWS CloudFormation might create IAM resources with customized names.

    Click Next to continue.

CRA Configure StackSet Options

  1. On Set deployment options page

    5a) Under Add stacks to stack set select "Deploy new stacks"

    5b) Under Specify deployment targets:

    • Option A: Deploy to organization for creating stacksets in entire org accounts

    CRA Set Deployment Options

    • Option B: Deploy to organization units to target specific accounts in OUs

      i) Specify AWS OU IDs

      ii) For Account Filter Type select intersection

      iii) In the Account Number field, specify AWS account IDs

    CRA Set Deployment Options

    5c) Under Auto-deployment options

    i) For Automatic deployment select Activated

    ii) For Account Removal Behaviour select Delete Stacks

    CRA Account numbers

    5d) Under Specify Region, choose your target regions (for example, us-east-1). Keep the default deployment options and click Next to proceed.

    CRA Specify Regions

  2. On the Review page, review the options and click Submit to create the StackSet.

CRA Deployment targets

CRA Deployment targets

Now you can create an AWS Integration connection in the APIsec platform using this Central ARN.

AWS API Gateway integration with the APIsec product​

Start adding a new application​


Select Amazon API Gateway​

  • Choose the Amazon API Gateway

    Choose the Amazon API Gateway

  • If existing connections are available, they will be displayed in the Connections list. To create a new connection, click New Connection.

  • If no connections exist, a connection form is displayed, allowing you to enter the required details and create a connection.

  • Click New Connection New Connection button

Enter application details​

You can onboard using three credential types:

  1. AWS User
  2. Assume Role
  3. Central Role ARN
  • Enter the following details for AWS User credential type

    • Name: Enter a unique name for the connection.

    • Credential Type: Select the type of credential to use as AWS User.

    • Access Key: Enter the AWS Access Key associated with your IAM user.

    • Secret Key: Enter the corresponding AWS Secret Key.

      AWS User connection details

  • Enter the following details for Assume Role credential type

    • Name: Enter a unique name for the connection.
    • Credential Type: Select the type of credential to use as Assume Role.
    • Role Arn: Enter the Amazon Resource Name (ARN)
    • Session Name:(optional) Provide a session name to identify the temporary security credentials used in this connection. Assume Role connection details
  • Enter the following details for Central Role ARN credential type

    • Name: Enter a unique name for the connection.
    • Credential Type: Select the type of credential to use as Central Role ARN.
    • Central Role Arn: Enter the APIsecCentralRole ARN.
    • Session Name:(optional) Provide a session name to identify the temporary security credentials used in this connection. Central Role ARN connection details
  • Click Test Connection

    Test Connection button

  • Test Connection successful

    Connection test success message

  • Click Create Connection

    Create Connection button

  • Select Region and API

    Select Region and API

  • Click Continue

    Continue button

  • Click Onboard

    Onboard button

  • Application Dashboard

    Application dashboard


Auto-Onboard​

The Auto-Onboard feature streamlines API onboarding by automatically detecting and registering unregistered APIs from AWS API Gateway. This ensures that all APIs, including newly published ones, are consistently onboarded and tested for vulnerabilities with minimal manual effort.

Enable Auto-Onboard​

  • Open your browser and visit: https://<your-tenant>.apisecapps.com

  • Click Integrations tab

    Integrations tab

  • Click Onboard Applications adjacent to the Amazon API Gateway

    Onboard Applications for Amazon API Gateway

  • Enable Auto-Onboard of any existing AWS connection.

    Auto-Onboard toggle

  • Fill in the AWS AutoOnboard Details and click Save Schedule

    • Frequency – How often the onboarding should occur. By default it is weekly.
    • Day of the Week – Select the specific day for onboarding.
    • Hour – The exact time (in hours and minutes) when the onboarding should start.
    • Timezone – The timezone in which the schedule should be applied
    • Region – The AWS region from which resources will be onboarded (applicable for credential types AWS User and Assume Role).
    • API Selection Scope - Select whether to auto-onboard all available APIs or limit onboarding to only those published after the specified date.

    AWS AutoOnboard details and Save Schedule button

  • Successfully saved auto-onboard details

    Auto-onboard saved confirmation

Update Schedule​

  • Open your browser and visit: https://<your-tenant>.apisecapps.com

  • Click Integrations tab

    Integrations tab

  • Click Onboard Applications adjacent to the Amazon API Gateway

    Onboard Applications for Amazon API Gateway

  • Click Auto-Onboard enabled toggle

    Auto-Onboard enabled toggle

  • Update the details and click Update Schedule

    Update Schedule button

Disable Auto-Onboard​

  • Open your browser and visit: https://<your-tenant>.apisecapps.com

  • Click Integrations tab

    Integrations tab

  • Click Onboard Applications adjacent to the Amazon API Gateway

    Onboard Applications for Amazon API Gateway

  • Click Auto-Onboard enabled toggle

    Auto-Onboard enabled toggle

  • In Edit AWS AutoOnboard Details, disable the Enable Automatic API Onboarding.

    Disable automatic API onboarding

  • Click Yes to confirm

    Confirmation dialog

  • Auto-Onboard details deleted.

    Auto-Onboard details deleted message

Edit AWS connection​

  • Open your browser and visit: https://<your-tenant>.apisecapps.com

  • Click Integrations tab

    Integrations tab

  • Click Onboard Applications adjacent to the Amazon API Gateway

    Onboard Applications for Amazon API Gateway

  • A list of existing AWS connections is displayed.

    AWS connections list

  • Select the Pencil icon next to the connection you want to edit.

    Pencil icon next to a connection

  • Update the required details and click Test Connection

    Test Connection button

  • Once the connection test succeeds, click Update Connection

    Update Connection button

  • The updated connection is now displayed in the connections list.

    AWS connections list

Delete AWS connection​

  • Open your browser and visit: https://<your-tenant>.apisecapps.com

  • Click Integrations tab

    Integrations tab

  • Click Onboard Applications adjacent to the Amazon API Gateway

    Onboard Applications for Amazon API Gateway

  • A list of existing AWS connections is displayed.

    AWS connections list

  • Select the Delete icon next to the connection you want to delete.

    Delete icon next to a connection

  • Click Delete to confirm

    Delete confirmation dialog

  • The deleted connection is no longer displayed in the connections list.

    Connections list after deletion