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.

What is an Access Key?

An Access Key is an API Key generated by the API to identify the source or user making a request to the Keen.

You can programmatically generate, revoke, or modify Access Keys. For example, if you wanted to have customer-facing analytics in your app, Access Keys would allow individual customers to see their own data without exposing anyone else’s data. Access Keys can also restrict where a user can send data or automatically include other data properties.

Each key has a defined scope of permitted operations. You can read more on how to create, revoke, or modify Access Keys below.

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? (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

You can white-label embedded analytics with Keen’s Visualization tools to create analytics for your customers quickly, securely, and beautifully. You can also create embedded dashboards and native analytics to display interesting data to your customers.

By customizing and specifying permissions via unique Access Keys, you gain fine-grained control over who sees your data. An 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’s Access features, you can leverage Keen’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.

Create an Access Key

Are you ready to create your first Access Key? There are two ways to create an Access Key: Via the User Interface and via the API.

Create Access Keys via the User Interface

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

Create Access Keys via the 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.

Customizing your Access Key

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

“writes” permitted

When “writes” are permitted, the Access Key will have the ability to stream data to Keen.

“queries” permitted

When “queries” are permitted, the Access Key will have the ability to do ad-hoc queries.

Note: This does not include saved, cached queries, or datasets.

“saved_queries” permitted

When “saved_queries” are permitted, the Access Key will have access to run saved queries.

If you need to create a saved query, update a saved query, delete a saved query, or anything else with a saved query that requires a Master Key, this cannot be done with an Access Key.

Note: If you have a saved query that is being cached, you will need to have “cached_queries” permitted.

“cached_queries” permitted

When “cached_queries” are permitted, the Access Key will have access to retrieve results from cached queries.

Note: If you have a saved query that is not being cached, you will need to have “saved_queries” permitted.

“datasets” permitted

When “datasets” are permitted, the Access Key will have access to getting a dataset definition, retrieving cached dataset results, and listing cached datasets definitions for a project.

Remember: If you need to create a cached datasets or delete cached datasets, this requires a Master Key and cannot be done with an Access Key.

“schema” permitted

When “schema” is permitted, you can inspect schema information for a single collection or all the event collections in a given project.

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": "Ada 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.id": ["93iskds39kd93id"]
          }
        },
        "my_other_dataset_unlimited_access": {}
      },
      "blocked": ["my_sensitive_dataset"]
    }
  }
}