As always, our first goal is to make analytics via API powerful but simple. We want to make your life as easy as possible. Like any good service, Keen IO takes security seriously. Unfortunately, there’s a direct conflict between ease-of-use and security. Effectively securing an API almost always means making that API harder to use.
There’s not a lot of room for compromise here. A system is either following cryptographic best practices or it’s not. We follow best practices. That being said, we want you to be happy. Please let us know if you’re not!
When you get your account, you’ll notice there are 3 different API Keys.
- Master Key - The most powerful API key. It can be used to authenticate for any API call. It is required to perform administrative functions, such as deleting data.
- Write Key - An API key specifically for writing data. Any API request that writes data to Keen IO can use this.
- Read Key - An API key for querying and extracting data. Used to run analyses and extract data from Keen IO.
All HTTP requests to Keen IO should be done over SSL. SSL is the industry standard for securing HTTP traffic. Our website defaults to HTTPS and we do not recommend non-SSL (HTTP) traffic to our API.
SSL secures everything in the HTTP payload, which includes potentially sensitive information (like your project ID), and definitely sensitive information (like your API Key).
Protecting Your API Key
Your Keen IO Master Key, along with your username and password, is the holy grail of Keen IO. If you have that, you have access to all Keen IO API features. This includes querying data, changing data, and even deleting data.
Never give your Master Key to anybody. Keen IO team members will never ask you for it. And you should never expose the Master Key to your users. So, just to be clear - be careful with it! :)
Luckily, you’ll never need to expose your API Key. Read on for more details.
Keen IO is used prominently in many clients (iOS, Android, Mobile Web, Desktop Web, etc.). Just like other analytics services, you embed a snippet of code into your application or site, and that snippet includes some identification about your account. At Keen IO, that’s your Project ID.
An unfortunate truth about client security is that any code embedded into a client is inherently not secure. The source can be viewed, decompiled, or unobfuscated. Or the binary itself can be analyzed. What this means is that you should NEVER embed secure credentials in your clients.
Keen IO breaks down its access paths into two modes - writing and reading. Writing, or sending events, requires your Project ID and a Write Key. Reading, or doing analyses, requires your Project ID and a Read Key. If you’re only using one of our clients to add events, don’t include your Read Key. And if you’re only using a client to do analyses, don’t include your Write Key.
The important thing here is that the Master API Key is NEVER required for the most common use cases. You should never embed your Master API Key in a client.
Unlike a client, you can actually secure your servers (go you!). This means you’re free to embed your Master API Key in your source code or configuration. One of the easiest ways to make sure your API Key never gets leaked is to proxy all API requests between your clients and Keen IO servers through your own servers. But maintaining a proxy is annoying and can get expensive as you grow (not to mention it’s a potential single point of failure). We have a solution to that.
Protecting Your Data
- How do I prevent somebody from sending events to Keen IO?
- How do I prevent a customer from performing administrative operations in Keen IO?
- How do I make sure customer A can’t read customer B’s data?
There’s no way to both allow clients to send data to Keen IO and prevent a malicious user of a client from sending bad data. This is an unfortunate reality. Google Analytics, Flurry, KissMetrics, etc., all have this problem.
The bright side of this is that Keen IO requires a Write Key to write data. And we can disable a write key if it’s being misused in some way. What this means for you is that you have more control over how data is being written to your Keen IO project.
Securing Administrative Operations
At Keen IO, only requests authenticated using your Master API Key can perform administrative operations (things like deleting data, creating new saved queries, etc.). So the simple answer is to NEVER give your Master API Key to anybody and to never expose it in a client. Because sending data to Keen IO doesn’t require your Master API Key, this is usually simple. But what if you also want to let your clients read data?
Keen IO queries can only be done by authenticated users. A request can be authenticated by two mechanisms:
Your API Key. This is appropriate if your requests are issued from your server. Otherwise you’ll be exposing your API Key, which is bad!
Keen IO leans on industry standards. To make security easier for our users, we’ve automatically generated both a Write and a Read Key. They’re listed on your project details page right next to your API Key. Feel free to use these.
An Access Key. This is a special API key that can be programmatically generated via API request to Keen IO. It applies filters you define to any query that is run while using that particular Access Key. This is helpful if you’re trying to expose data to your users, but you don’t want them to have access to anyone else’s data. The process of generating an Access Key is below.
Access Keys and Security
When To Generate an Access Key
If you’re serving analytics to your users, you’ll want to generate an Access Key. It is best practice to create this Access Key once as part of your customer’s onboarding, aka when a user/account is created in your application. To help you keep track of Access Keys you created, you can check the Access Key Table in our User Interface or retrieve a list via our API.
For a more in-depth view of when it may be appropriate to create an Access Key see our Access Key Guide.
Generating an Access Key
Use the Keen IO to generate an Access Key with the permissions you want. This can be done via the Access Keys UI under Settings, or via our API. A unique key in string format will be generated.
Take that string and use it in place of your API Key.
Keen IO will see the permissions and options defined in your custom Access Key. If you defined any filters, we will automatically apply your filters defined in your Access Key to your queries. So, for example, you can create customer-specific keys that automatically add the customer filter to all read analyses.
Notes on Access Keys
Depending on how you generate it, an Access Key can either do writes or reads (or both). It can never do admin operations (like deleting data). Access is determined by the value you include for the “permitted” property. Its value should be a list of strings. Valid values for writing are: “writes”. Valid values for different types of reads are: “queries”, “saved_queries”, “cached_queries”, “datasets”, and lastly, “schema” (which lists project metadata). For a more details on Access Keys see our Access Key Guide.
At the end of the day, the ONLY thing an Access Key can do is what you tell it to do. But it can’t delete data and it can’t perform any admin requests. So rest easy knowing that giving your user an Access Key is secure.
If you regenerate your API keys, all of the Access Keys you’ve created will remain valid.
Our server-side SDKs (Ruby, Python, Java, Node.js) have built-in methods to make generating an Access Key a one-line affair. Our goal is to make this work as transparent as possible. If you’re frustrated by this, we’ve failed. Please let us know so we can make it right for you! Contact us!