Manage Api Keys

EventBunker has support for multi projects under one account. This enables you to leverage your single EventBunker account under one billing for many of your separate projects as a serial entrepreneur.

Using management api, you can create project, reset project master key and delete projects. Check out Managing Projects for that.

In this page, you will find the documentation for how to create and delete api keys of a project. A Project can have 1000s api keys, while you can of course use web ui to do all of these actions by clicking buttons, for big scale usage of EventBunker, it is convenient to call api to manage api keys. You will include this api key in the request header for Track Events and Query API methods.

tip

You will use your project master key for api key management apis, please copy the key from Project page

Before reviewing the api methods, let's talk about two use-cases for api keys.

How to Use Api Keys

There are 3 types of api keys; QUERY, WRITE and DELETE

And each of these 3 types can also have customer_identifier or not based on your use-case.

api keys without customer_identifier are able to access all data in that project.
api keys with customer_identifier have limited access scope to customer_identifier's value, eg. read data with single customer filter and write events with customer_identifier auto filled by api.

1- Let's talk about this example scenario, you want to use api keys in a front-end application for reading(querying) data and/or writing(tracking) events from frontend application. In both cases your EventBunker api key will be visible in page's source code and someone can get this api key and use it to query other customer's data if they know about your customer identifiers, maybe an increment number, maybe already visible in public profile pages. To prevent this cross customer data access we have customer_identifier field in EventBunker.

As a solution, you can create your query keys with a key_filter_data field as described below and write keys with a key_insert_data field. This will limit the data access permission of that api key to given single customer id, so even someone trys to change filter values in query requests, api will not provide other customer's data. You can also completely omit having customer_identifier field in write and query requests since this field will be overwritten with the customer_identifier value from api key's key_insert_data for WRITE keys, key_filter_data for QUERY keys.

It is also possible to limit read access for certain pre-defined event names, using event_names field in key_filter_data.

2- In a different scenario, when you need to analyze event data without any customer_identifier limit, like you create a report where customers can not access or modify source code, which means api keys can not be seen by anyone other than you. Or when you query EventBunker api from your backend and later pass the response to your frontend, again keys will be in your backend code where customers can not see. (Please avoid having keys in error or log messages, visible to users) In this case, you do not have to use key_insert_data or key_filter_data so a single api key can access all data of that project which api key belongs to.

tip

You will use your project master key for api key management apis, please copy the key from Project page

Create Api Key

Mandatory and optional fields are used in create request;

Field Name	Type	Required	Description
project_id	String	Yes	Your project id
api_key_type	String	Yes	QUERY, WRITE or DELETE
description	String	Optional	A descrition of api key
key_insert_data	JSON Object	Optional	For WRITE keys, to set customer_identifier
key_filter_data	JSON Object	Optional	For QUERY and DELETE keys, limiting access permissions

Endpoint;

POST https://api.eventbunker.io/v1/manage/api-key/create

Example Request;

Please copy your project id and master api key from web ui and replace with placeholders in example code below. Copy and run the sample code below in your terminal window. key_insert_data is only used for WRITE keys and key_filter_data is only used for QUERY and DELETE keys.

curl --request POST 'https://api.eventbunker.io/v1/manage/api-key/create' \
--header 'x-eventbunker-apikey: <YOUR-PROJECT-MASTER-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": <YOUR-PROJECT-ID>,
    "api_key_type": "WRITE",
    "description": "Sample api key description",
    "key_insert_data": { "customer_identifier": "example_cust_id_000" },
    # or for QUERY keys
    "key_filter_data": { "customer_identifier": "example_cust_id_000", 
                        "event_names": ["event1", "event2"] 
                      }
  }'

Example Response;

Response will be a JSON contaning your new api key. You will include this key in the request header for Track Events and Query API methods.

{
  "project_id": "your project's id",
  "api_key": "your new api key",
  "api_key_type": "api key's type",
  "status": "ACTIVE"
}

That's it! Congratulations, you have created your first api keys. You can implement this request in any language since it is just a http post request to EventBunker api endpoint.

List Api Keys

If you need to list api keys of a project, you can use following request example to get all active keys per api key type of a project. This may be used to get list of keys to delete in next delete key api calls.

Mandatory and optional fields are used in create request;

Field Name	Type	Required	Description
project_id	String	Yes	Your project id
api_key_type	String	Yes	QUERY, WRITE or DELETE

Endpoint;

POST https://api.eventbunker.io/v1/manage/api-key/list

Example Request;

Please copy your project id and master api key from web ui and replace with placeholders in example code below. Copy and run the sample code below in your terminal window.

curl --request POST 'https://api.eventbunker.io/v1/manage/api-key/list' \
--header 'x-eventbunker-apikey: <YOUR-PROJECT-MASTER-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": <YOUR-PROJECT-ID>,
    "api_key_type": "WRITE"
  }'

Example Response;

Response will be a JSON contaning list of api keys by requested type.

{
  "project_id": "your project's id",
  "api_key_type": "api key's type",
  "api_keys": ["apikey_1", "apikey_2"]
}

Delete Api Key

If you no longer need an api key, you can delete it from your project via this api. Api key will not be usable anymore and will be deleted from databases. You can always create a new one, but new key will be with a different key value of course.

caution

After calling delete api, Api Key will not be usable anymore and will be deleted from caches and databases in 5 minutes.
This is an irreversible action!

Mandatory and optional fields are used in this request;

Field Name	Type	Required	Description
api_key	String	Yes	Your api key to delete
project_id	String	Yes	Your project id this key belongs to

Endpoint;

POST https://api.eventbunker.io/v1/manage/api-key/delete

Example Request;

Please copy your project master api key from web ui and replace with placeholders in example code below. Copy and run the sample code below in your terminal window.

curl --request POST 'https://api.eventbunker.io/v1/manage/api-key/delete' \
--header 'x-eventbunker-apikey: <YOUR-PROJECT-MASTER-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "<YOUR-PROJECT-ID>"
    "api_key": "3fbd4bd0-ba7f-49d6-b9d5-b77f99999999"
  }'

Example Response;

Response will be a JSON confirming your api key status.

{
  "api_key": "your deleted api key",
  "project_id": "your project id",
  "status": "DELETED"
}

You will get an error if this api key does not exist. Api key will not work anymore, this will happen in maximum 5 minutes because of caching.

Error Codes

For a general explanation of error codes please read here in project management

For all api methods in api key management you can possibly get the following errors with HTTP 400 error code in addition to list in linked page.

Invalid key_insert_data. Please check docs for correct format
Invalid key_filter_data. Please check docs for correct format
Can not modify inactive project
Too Many Requests (if you exceed rate limit, which is very high)

How to Use Api Keys​

Create Api Key​

Endpoint;​

Example Request;​

Example Response;​

List Api Keys​

Endpoint;​

Example Request;​

Example Response;​

Delete Api Key​

Endpoint;​

Example Request;​

Example Response;​

Error Codes​

How to Use Api Keys

Create Api Key

Endpoint;

Example Request;

Example Response;

List Api Keys

Endpoint;

Example Request;

Example Response;

Delete Api Key

Endpoint;

Example Request;

Example Response;

Error Codes