API Gateway Permissions Model is Special


Amazon's new API Gateway service has great potential, probably an avenue for future expansion of AWS, and certainly something I'm trying to get up to speed on. But API Gateway definitely has some quirks.

Today, I ran into a strange aspect of the permissions model for API Gateway while answering a StackOverflow question about why the documented permissions didn't work in the IAM Policy Simulator , and it's still bothering me. Amazon made an intersting choice with the permissions model that seems consfusing to developers and fateful with respect to future services. In short, I would call it "special", for not being with the same program every other AWS service used to define their permissions.

The bottom line is that API Gateway has its client and admin/management permissions broken out under different service names. When you look at the list of services for permissions, you see:

  • API Gateway - Permissions for clients, currently the only action is `execute-api:invoke`.
  • Manage - API Gateway - Admin permissions for configuring the API Gateway, which has CRUD actions fitting the `apigateway:*` spec.

In the IAM Policy Simulator:

AWS Services in Policy Simulator

But it's not just the simulator, the IAM permissions really are broken out this way.

This is unlike every other service I am familiar with, where the client and admin/management permissions exist as different actions under the same service name. I hope this is not a precedent Amazon extends to other services.

I don't understand why Amazon did this. At least not yet. API Gateway is a new service, the glue might not be dry, and I'm sure they are expecting to make some changes from feedback. However, this split seems too visible not to have gone through some discussion already. Starting with all the conversations with the Management Console UI team where they say "we need two entries in the service list", and the UI guys reply "Two entries? WTF!? Are you special?" I paraphrase only a little.

Looking at the IAM Policy Generator's list of action namespaces shows just how strange this is. Normally, you just have to scroll through the list far enough to find out if your services starts with Amazon or AWS. That's already strange. Now the Manage - Amazon API Gateway not only appears at the very bottom of the list, but it appears after Amazon API Gateway halfway through. And the list is big enough that the two do not appear visible on the same screen at the same time.

IAM Policy Services List

Only very persistent people will figure this out without asking for help, and many are likely to get frustrated and confused. For that reason, I expect Amazon will have to change something to make this more intuitive.

If anyone knows the logic behind this move, please share!