home shape

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


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.


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.

Michael Hackstein

Michael is a JavaScript and NoSQL enthusiast. In his spare time he is organising colognejs, the JavaScript user group in Cologne Germany scheduled every second month. In his professional life Michael holds a master degree in Computer Science. As Front End Specialist he is member of the ArangoDB core team, developing the web frontend and graph visualisation for this project. He is conference and user group addicted.


  1. Andy on February 4, 2016 at 9:18 pm

    Does the api-keys app have any security itself? Presumably you’ll be using this if your foxx apps aren’t requiring any other authentication? In which case the key manager will also be exposed?

    • Michael Hackstein on February 5, 2016 at 3:22 pm

      You are totally right, the api-keys app was meant to be a quick and minimal show-case on how to technically do it. For production use it should of course have it’s own authentication. I am going to update the app and add security to it. Thanks for spotting it.

Leave a Comment

Get the latest tutorials, blog posts and news: