Connect AWS API Gateway

You connect Amazon API Gateway through the guided setup. It asks how you want to create the IAM role that Apiable uses, helps you create that role in your AWS account, then tests it and saves the gateway. You never give Apiable an access key or secret: Apiable assumes the role.

Where do you start connecting Amazon API Gateway?

From any of three places. Each opens the guided setup's Gateway step, which has three screens: Choose method, Create the role and Confirm connection.

• Integrations → Integrations: choose Set up on the Amazon API Gateway card.
• Integrations → API Gateways: choose + Add Gateway, select Amazon API Gateway on Select API Gateway Type, and click Connect new API Gateway.
• Getting Started: click Run the wizard. This is the usual start for your first gateway.

You no longer choose between Basic and Advanced. How authorization is enforced is chosen later, in the guided setup's Authorization step.

If a gateway is already connected, Run the wizard shows Your gateway is already connected, and Continue takes you to the next step. To connect another Amazon gateway, start from the card or from + Add Gateway.

Which method should you choose?

CloudFormation, unless you need to create the role by hand. Every method creates the same IAM role in your AWS account; only the tool differs.

On How would you like to connect your AWS account?, CloudFormation is selected for you. See what this creates explains what the role is before you start.

How do you create the role with CloudFormation?

Choose CloudFormation, set the region your API Gateway runs in, launch the stack in AWS, then copy the role ARN from the stack's Outputs tab.

1. On How would you like to connect your AWS account?, keep CloudFormation selected and click Continue.
2. On Create the role in AWS, set Region to the region your API Gateway runs in. It starts at us-east-1 unless you chose a region earlier.
3. Click 🚀 Launch Stack →. AWS CloudFormation opens in a new tab on the stack review page, with Apiable's published template, the stack name apiable-gateway-role, and Apiable's AWS account and egress address already filled in.
4. In AWS, review the stack, acknowledge that it creates an IAM role with a custom name, and create the stack.
5. When the stack is complete, open its Outputs tab. The stack has one output, and its value is the role ARN. Copy it.
6. Back in Apiable, click Continue.

If your browser blocks the new tab, Apiable shows an Open the AWS Console link to the same page. If you see We could not reach Apiable to prepare your launch link. Please try again., click Try again.

How do you create the role in the AWS Console?

Choose Console. Apiable shows the trust policy, permission policy and role name for your region. Create the role in the IAM console with those values, then copy its ARN.

1. On How would you like to connect your AWS account?, select Console and click Continue.
2. On Set up the role in the AWS Console, set Region to the region your API Gateway runs in. The values on the screen update for that region.
3. Follow the steps the screen lists. In the IAM console, choose Create role, then Custom trust policy, and paste the Trust policy. Attach the Permission policy as a new customer-managed policy. Name the role exactly as shown under Role name. Review and create the role.
4. Open the new role in the IAM console and copy its ARN.
5. Back in Apiable, click Continue.

Each value has a Copy button, and Open the AWS Console opens the IAM roles page. The screen also shows the Platform account ID that the trust policy names, and the Apiable egress address, which is already included in the permission policy.

What does the IAM role allow?

Apiable's AWS account can assume it. It reads your REST APIs and manages only API keys and usage plans. Everything else is denied, including HTTP and WebSocket APIs and any call from outside Apiable's egress address.

Apiable assumes the role with AWS Security Token Service, using the session name GatewaySetupAssumeRole. The role is named apiable-gateway-management-role-<region>. Both methods above create it with the two policies below.

Trust policy

The trust policy names the Apiable AWS account 034444869755 as principal and allows sts:AssumeRole.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::034444869755:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Permission policy

Apiable never writes to your APIs. It creates no deployments, changes no stages or methods, and imports nothing, which is why read access to /restapis is enough.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadRestApisOnly",
      "Effect": "Allow",
      "Action": "apigateway:GET",
      "Resource": [
        "arn:aws:apigateway:REGION::/restapis",
        "arn:aws:apigateway:REGION::/restapis/*"
      ]
    },
    {
      "Sid": "ManageApiKeysAndUsagePlans",
      "Effect": "Allow",
      "Action": ["apigateway:DELETE", "apigateway:GET", "apigateway:PATCH", "apigateway:POST"],
      "Resource": [
        "arn:aws:apigateway:REGION::/apikeys",
        "arn:aws:apigateway:REGION::/apikeys/*",
        "arn:aws:apigateway:REGION::/usageplans",
        "arn:aws:apigateway:REGION::/usageplans/*"
      ]
    },
    {
      "Sid": "TagUsagePlans",
      "Effect": "Allow",
      "Action": "apigateway:PUT",
      "Resource": "arn:aws:apigateway:REGION::/tags/*"
    },
    {
      "Sid": "DenyHttpAndWebSocketApis",
      "Effect": "Deny",
      "Action": "apigateway:*",
      "Resource": [
        "arn:aws:apigateway:REGION::/apis",
        "arn:aws:apigateway:REGION::/apis/*"
      ]
    },
    {
      "Sid": "DenyOutsideApiableEgress",
      "Effect": "Deny",
      "Action": "apigateway:*",
      "Resource": "*",
      "Condition": {
        "NotIpAddress": { "aws:SourceIp": "APIABLE_EGRESS_CIDR" }
      }
    }
  ]
}

Here REGION is your gateway's region, for example eu-central-1, and APIABLE_EGRESS_CIDR is the Apiable egress address. The CloudFormation stack fills both in for you, and the Console method shows the policy with both already filled in.

What each statement is for: API keys and usage plans are what Apiable manages. That is how subscriptions are deployed and rate limits applied. They do not live under /restapis, so a policy scoped to /restapis alone lets your APIs import and then fails every subscription approval. That is the most common mistake when writing this policy by hand. Tagging usage plans is optional, and Apiable works without it if you leave out /tags/*. The final statement pins the role to Apiable's egress address, so API Gateway calls made with the role from any other address are denied.

How do you confirm the connection?

Paste the role ARN, check the region, and click test. When the result reads Connected, Apiable has saved the gateway and you can continue.

1. On Confirm the connection, paste the role ARN into Role ARN. Three checks turn green as you type: Starts with arn:aws:iam:, Contains :role/ and Account ID is 12 digits.
2. Check AWS Account ID. Apiable reads it from the ARN, and shows Not yet derived until the ARN is complete.
3. Check AWS Region. It starts at the region you chose on the previous screen, and must be the region your API Gateway runs in.
4. Click test. It becomes available once all three checks are green.
5. When the result reads Connected, Apiable has saved the gateway. Click Continue.

Continue stays unavailable, with Test the connection to continue, until the test passes for the ARN on screen. If you change the ARN or the region, test again.

Apiable saves the gateway under a generated name that starts with wizard-onboarding-. To give it a clearer name, open it from Integrations → API Gateways afterwards, as described below.

What happens after the connection is saved?

Apiable imports your REST APIs and their stages into Catalog → API Catalog, and the guided setup moves on to its remaining steps. You can close it and come back later with Resume setup.

• Your APIs. Each deployed stage of a REST API appears as its own API, named after the API and the stage, for example Orders - prod. Add them to a plan from the API Catalog. See APIs and coupling. If they do not appear, check the region, and click Synchronize on the API Catalog.
• Authorization. The guided setup's Authorization step, Choose your authorization enforcement model, sets how authorization is enforced on this gateway: Native gateway enforcement, Lambda authorizer, Backend enforcement or External authorization server. If it shows This gateway can only use built-in authorization, choose Native gateway enforcement or connect a new gateway. See Authorization Servers.
• The rest of the setup. The remaining steps cover Authentication and Access Control. See the onboarding plan.

To leave, close the guided setup. It returns you to Getting Started, and asks Leave the wizard? if you have unsaved changes.

How do you edit a saved Amazon gateway?

Open it from Integrations → API Gateways. Its Details tab has Name, AWS Account ID, AWS Region and Role ARN. Change what you need, run the test, then click Save Changes.

1. Open Integrations → API Gateways and click the gateway's name.
2. On the Details tab, change the fields you need.
3. Click the refresh icon labelled test. The result reads Connected or Unsuccessful.
4. Click Save Changes.

If your role cannot manage gateways, the form shows Your account does not currently possess a sufficient role or permissions required to manage gateways. and you cannot save changes.

How do you point the AWS gateway at an Authorization Server?

Open the saved gateway and go to its Authorization tab. Under OAuth handler, choose Gateway-native only or Authorization Server. Picking Authorization Server reveals a picker of your connected servers. Click Save Changes to apply.

The tab also has the Level 0 API Key section and Product-level governance. See API Gateways for what each part does, and Authorization Servers for connecting a server.

How do you meter usage on AWS for billing?

Stream the stage's access logs to Apiable. Connecting the gateway deploys subscriptions and applies rate limits, but gives Apiable no per-request usage. Usage logs add it, and usage-based billing and per-subscription analytics run on them.

You create a logs bucket and a Kinesis Firehose stream in your AWS account, point the stage's custom access logging at the stream, and paste a one-line JSON log format. Apiable attributes each call to a subscription from subscription_id, or from the API key's key_id when subscription_id is not set, and ingests the delivered files about once an hour. You email the bucket details to support@apiable.io so Apiable can connect ingestion to your bucket. See Enable usage logs on AWS API Gateway for every step, then Monetization to turn usage into invoices.

How do you pull an API specification from AWS?

With Gateway Synchronization in a plan's documentation settings. It works only when the plan's gateway is an Amazon API Gateway. On a catalog-led portal, documentation follows each API's API Catalog entry instead.

See Attach documentation to a plan for the documentation sources a plan can use.

What does Amazon API Gateway support in Apiable?

Everything in the core flow, plus the per-key operations and gateway reads the other gateways do not implement.

• Import your REST APIs and their stages into the API Catalog.
• Deploy plans as usage plans, and add each subscription's API key to its plan's usage plan.
• Enable or disable an individual API key.
• Check that a plan is set up correctly on the gateway.
• Read usage per plan and per key from the gateway.
• Include only some resources of an API in a plan.
• Pull API specifications with Gateway Synchronization.
• Stream access logs for usage-based billing.

Rotating a subscription's secret is not available on standard setups. Use Regenerate Credentials on the subscription instead: Apiable revokes the current credentials and issues new ones. See Credentials.

Troubleshooting

Match what you see to the fix.

Where to next