Access Keys

The purpose of this guide is to help you understand how to safely and securely share your analytics with your customers. This guide covers what is and when to create an Access Key. To create and manage your Access Keys, see code samples in our API Reference Documentation.

Access Key Best Practices

What is an Access Key? An Access Key is an authentication key generated by the API to identify the source or user making a request to the Keen IO platform service. The key is used to authenticate requests to your data.

When you get your account, you’ll notice each project has it’s own API Key: This is the “Master Key”. It can be used to authenticate any API call and is used to perform administrative functions, such as deleting data. Protect this Key!

It is best practice not to use your Master Key in a production environment.

Data security - Create a Read & Write Key

In order to protect the quality of the data you’re collecting and who has access to it, you will be creating custom access keys to protect it.

It is a best practice to create specific access keys for writing data or reading data to Keen. You will be making at least one Read Key and one Write Key.

Sample Write Key

{
  "is_active": true,
  "name": "WRITE_KEY",
  "permitted": [
    "writes"
  ]
}

Sample Read Key

{
  "is_active": true,
  "name": "READ_KEY",
  "permitted": [
    "queries",
    "saved_queries",
    "cached_queries",
    "datasets",
    "schema"
  ]
}

Other Use Cases for Access Keys:

Aside from assigning a specific Access Key for read and write. Access Keys can be used to further customize and fine-tune access to your projects. They can be defined to limit collection and query abilities to a tighter timeframe, filter, or specific type of data. Because you can control and restrict the ability to write data to particular streams or access to results of particular queries, Access Keys add a layer of security to your event data architecture.

Some additional use cases where you may want a custom Access Key:

  • How do I ensure that customer A & customer B’s data do not mix?
  • How do I make sure customer A can’t read customer B’s data?
  • How do I prevent a customer from performing administrative operations in Keen IO? (such as deletes)
  • You’re presenting a dashboard to a specific user and want to make sure that another user cannot see that user’s data.
  • You want to allow certain queries to be accessible to certain users, but not others.
  • You would like to provide your customer’s admins with an unlimited token, and then give them the control to determine which team members have access to the most proprietary data.

In these examples, Access Keys are being used to define and manage fine-grained permissions for who can access which streams and analyses. The resulting custom permissions guarantees that each of your users can only explore the data they need because their permission credentials can be specified.

Deep Dive: Power White-label Embedded Analytics Securely

Whitelabel Keen IO’s Visualization Solution to create analytics for your customers quickly, securely, and beautifully. You can create embedded dashboards and native analytics to display interesting data to your customers.

Use custom Access Keys to define several layers of access for your users. By customizing and specifying permissions via unique API Access Keys, you gain fine-grained control over who sees your data. A custom access key helps you maintain compliance when presenting customer facing dashboards.

Specific keys can be created with access rules that can restrict access to data based on properties like CustomerID or PaymentPlan. By using Keen IO’s Access features, you can leverage Keen IO’s security features to present data in arbitrary ways without having to re-architect your security or data model to create value differentiation in your offering by selling varying levels of data access.

Customizing your Access Key

The following customization is available when creating a specialized Access Keys. The custom Access Key’s options are represented as a JSON object with the following properties. Each of the properties can be set for your use case:

Property Type Description
name string A human readable name for the API key. Limited to 256 characters.
is_active boolean Indicates if the key is currently active or revoked.
permitted list A list of high level actions this key can perform. Possible options: “writes”, “queries”, “saved_queries”, “cached_queries”, “datasets”, “schema”
options object An object containing more details about the key’s permitted and restricted functionality.
options.writes object Container object for write options.
options.writes.autofill object An object containing properties to be merged with properties sent during data collection.
options.queries object Container object for query options.
options.queries.filters list A list of filters that are automatically added to every query.
options.saved_queries object Container object for saved_query options.
options.saved_queries.allowed list A list of saved_query names this key is allowed to access.
options.saved_queries.blocked list A list of saved_query names this key cannot access.
options.saved_queries.filters list A list of filters added to every saved query retrieved.
options.cached_queries object Container object for cached_query options.
options.cached_queries.allowed list A list of cached_queries this key is allowed to access.
options.cached_queries.blocked list A list of cached_queries this key cannot access.
options.datasets object Container object for Cached Dataset options.
options.datasets.operations list List of possible operations - “read”, for getting definition; “list”, for getting multiple definitions; “retrieve”, for getting results], create/delete require Master Key
options.datasets.allowed object Cached Datasets this key can access, with optional limiting of “index_by”
options.datasets.blocked object Cached Datasets this cannot access

Access Key: JSON Example

{
  "name": "This is my human_readable string name!",
  "is_active": true,
  "permitted": ["writes", "queries", "saved_queries", "cached_queries", "datasets", "schema"],
  "options": {
    "writes": {
      "autofill": {
        "customer": {
          "id": "93iskds39kd93id",
          "name": "Acme Corp."
        }
      }
    },
    "queries": {
      "filters": [{
        "property_name": "customer.id",
        "operator": "eq",
        "property_value": "93iskds39kd93id"
      }]
    },
    "saved_queries": {
      "allowed": ["my_saved_query", "my_other_one"],
      "blocked": ["my_sensitive_query"],
      "filters": [{
        "property_name": "customer.id",
        "operator": "eq",
        "property_value": "93iskds39kd93id"
      }]
    },
    "cached_queries": {
      "allowed": ["my_cached_query", "my_other_one"],
      "blocked": ["my_sensitive_query"]
    },
    "datasets": {
      "operations": ["read", "list", "retrieve"],
      "allowed": {
        "my_single_index_dataset": {
          "index_by": {
            "customer_name": ["ted"]
          }
        },
        "my_other_dataset_unlimited_access": {}
      },
      "blocked": ["my_sensitive_dataset"]
    }
  }
}

Create an Access Key

Ready to create your first Access Key?

Create Access Keys via the User Interface

Access Keys can be generated, revoked or modified via the Keen IO User Interface. For step-by-step instructions, see our detailed How-To Guide on Creating a New Access Key via the UI.

Edit then Save API Access Key

Create Access Keys via the Keen IO API

You can also create Access Keys programmatically via our lovingly-crafted API. It is best practice to create one for each of your customers as a part of your customer’s on-boarding flow into your product. To find and execute the commands for creating keys via the API, see our API Reference Guide.