Securing your Foxx with API Keys

ArangoDB’s Foxx allows you to easily build an API to access your data sources. But now this API is either public or restricted to users having an account, but those still get unlimited access.

In many use cases you do not want to expose your data in this fashion, but you want to expose it with a more controllable access pattern and want to restrict the requests one user could issue in a certain time period. Popular examples for these API restrictions are Twitter or Facebook. This allows you to offer all of your data but only in limited chunks, and then possibly charge your customers to increase the chunk limit they can request.

All this is done via API keys, which are bound to a user and has become a common pattern to monetize the data you have collected.

In order to make this as simple as possible in Foxx we have created an API key Foxx for you that allows you to manage the API keys you have issued and can be imported in any of your Foxxes. This library make it as simple as add a single line per endpoint to make sure everything is handled via the API keys.

curl http://localhost:8529/_db/_system/weather/day/50674?apiKey=TZedR346HQ1l7p

In order to manage the API keys we want to introduce two concepts that we used in our API key library: plans and buckets

Buckets

A bucket defines a namespace for Foxx routes and is used to count how many requests can be issued by an API key user. As one example I want to distinguish between single entity reads and complex queries.

To secure my API in that way I have to create two buckets single and complex. Then I can add either or to one endpoint to make sure the correct counter is taken. I can optionally increase the amount that is added to the counter for each request. This is useful in the case when I have a route that should be more expensive than other routes.

Plans

A plan defines refresh rates for the buckets and actually describes the different types of users I want to allow.

It can define the refresh rates of arbitrary many of my buckets, but it does not have to define all of them. If one bucket is not refreshed in a plan no requests to routes using this bucket are allowed. I can define refresh rates for hours, days and months in any combination.

To give you an example: I have a free plan that should allow a user to issue 5 single and 1 complex query per hour, then I define the plan as follows:

single: {
  hour: 5
},
complex: {
  hour: 1
}

As you see I have not given day and month as I do not want to make any restriction here. But I also have a Premium plan allowing 20 single requests and 4 complex requests per hour, but at most 20 complex per day. Then the plan is the following:

single: {
  hour: 20,
},
complex: {
  hour: 4,
  day: 20
}

Whenever a route is triggered using complex bucket in a Premium plan the counter will be increased on hour and on day at the same time, if one of them now hits the limit the request will be blocked, even if there is a lot left on the other limit.

API Keys

Finally I want to issue new API keys for my customers. I can use the library to spawn new API keys from a specific plan and give them ot to my customers. Also I can change the plan attached to one API key during runtime and disable the API key.

How To Recipe

If you like to get some more detailed information and want to get hands-on experience I have written a small recipe on how to integrate the API key library into your Foxx.