# API Keys

API authentication is performed by generating API keys. There are two types of API Keys:

  1. Personal These keys are only visible to the user who creates them and are typically used for testing purposes.
  2. Org-Wide These keys will be visible to all users, but you can restrict who can create/modify them.

You can create as many API keys as you need. Use different API keys for different purposes. For example:

The API key used to send data in from your production environment(s) should be different than the API key used for testing.

For security purposes, you may choose to create multiple keys for the same purpose and rotate them.

  • You may choose to create seperate API keys to allow you to revoke permissions on one key without affecting the abilities of others.
  • You can create specific keys for deploying to client devices that only has Write permission and cannot read your metric results.

# Creating an API Key

To create a new API key, navigate to the API Keys page and select the + Add New button.

You have the following options when creating a new API Key or managing an existing one:

Option Description
Name Provide a name that describes the purpose of this key for you and your team to remember.
Org-Wide :check: Org-Wide keys are recommended for production use. Organization Admins can restrict who has access to modify Org-Wide keys.
Permissions Select whether this key has Read and/or Write permissions. See below for more information.
Enabled You can opt to disable (or enable) an API Key. This can be useful when rotating keys.

# Permissions

You can give an API Key Read and/or Write permissions.

In case you are including your Aggregations.io API key in a distributed client (like a mobile app) - it makes sense to utilize a separate key with permission to Write from one with permission to Read (for use with the Metrics API or Grafana Plugin).

In the future, we'll we adding additional capabilities and permission capabilities to individual API Keys.

# Managing API Keys

API keys can be viewed & edited on the API Keys page. By default, only enabled keys will appear in the table. To show all keys, select the filter icon and toggle the Disabled in the drop down menu.

You'll be able to see all org-wide keys as well as your personal keys. If you're an Admin (or have the proper permissions) you'll be able to see and edit Personal keys belonging to other users.