This article explains how to generate your public and private API keys.

	In This Article
	What Is the API? Generating API Keys Accounts and API Keys Generating Your API Key Pair Setting Up Integrations Frequently Asked Questions Additional Resources

What Is the API?

API stands for "application programming interface". An API allows for communication with an application without using the normal user interface. This comes in handy when two separate applications need to communicate and share information.

Emma has an open API, which allows developers to create integrations with our platform. For information, see the articles below.

• Creating Integrations Using Our API
• Emma Integrations
• Emma Technology Partners

Generating API Keys

Whether you're using a third-party integration or building your own, you'll need an API key pair in order to get started. API keys are credentials that help ensure that no one can send API calls to your account without permission. An API key pair consists of a public API key and a private API key, similar to a username and password. Both keys are required in order for an API call to work.

Accounts and API Keys

In Emma, API key pairs are generated on a per-user basis, not a per-account basis. This means that when you generate an API key pair, it will work for any account that your username has permission to access.

For example, if you are the Parent of a tiered account, you have access to all current and future subaccounts; thus, when you generate an API key pair, it will work for all current and future subaccounts. Similarly, if a Manager of a tiered account has access to 5 subaccounts, then their API key pair will work for those 5 subaccounts, but it will not work for any other subaccounts.

✎	Note
	You do not need to generate a new API key pair for each subaccount. In fact, it's better to not; when you regenerate your API key pair, your previous pair breaks. As a result, any integrations set up with the old API key pair will fail until they are given the new API key pair.

 

This method works because all of Emma's API calls require the account ID or subaccount ID to be included as part of the call. As a result, you can use the same API key pair for all of your subaccounts without a call being sent to the wrong subaccount. Emma does not use the API key pair to determine which subaccount the call should go to, it uses the account ID included in the call.

Generating Your API Key Pair

To generate, regenerate, or delete your API key pair, follow these steps:

1. Click on the gear icon in the upper right corner of your screen and select Profile from the dropdown menu.
2. Click on the API key tab.
3. To generate your API key pair, click on the Generate button.

If you have already generated an API key pair, you can click on Regenerate API key to break your existing key pair and generate a new one; or you can click on Delete API key to delete your existing API key pair without generating new keys.

⚠	Warning
	Your private API key will only be shown once: when you generate the key pair. Once you navigate away from the page, your private API key will never be visible again. Emma does not have a way of retrieving your private API key, so it is vital that you record your public and private API keys somewhere safe. If you lose your private API key, you will need to regenerate your keys.

Setting Up Integrations

When you set up a third-party integration with a tiered account, you must make sure that you give the integration the correct subaccount ID. If you give the integration the parent account's ID, it won't be able to send or receive the correct information. If you want to use an integration with multiple subaccounts, that integration will need to set up independently for each subaccount, with each subaccount's ID.

Frequently Asked Questions About API Keys

Where can I find your API documentation?

You can find our API documentation at the links below.

• Primary API Documentation
• API Calls by Category
• Event API Documentation
• Creating Integrations Using Our API

 

I've lost my private API key, can you recover it for me?

No. For security reasons, we do not store private API keys. As a result, they are not retrievable and we cannot help you recover a lost private API key. It's possible that one of your existing integrations may have a record of your private API key somewhere, but if not, you'll need to regenerate your API key pair.

Another option would be to create a new user and have them generate a new API key pair. This would leave your existing API key pair intact so that your integrations continue to run, while still providing you with a full set of credentials to set up new integrations.

 

What happens to an API key pair if the user who generated it is deleted?

If the user who generated the API key pair is deleted, then their API key pair will break and will no longer be usable. Any integrations using that API key pair will need to be reconnected with a new API key pair.

 

Can I generate an API key that is not connected to a user?

No, it is not currently possible to generate an API key pair that is not connected to a specific user.

For this reason, we recommend that you choose the API key pair that you use in integrations with care. It may be helpful to create a user with a generic, future-proof username, for example info@domain.com or IT@organization.edu, and have that user generate the API key pair for your integrations. For a tiered account, ideally this would be the account Parent or a Manager with access to all current and future subaccounts. This way, when a user leaves your organization, you can delete their personal username without needing to worry about API keys, because the generic username that generated the API key pair can remain.

Additional Resources

• Primary API Documentation
• API Calls by Category
• Event API Documentation
• Creating Integrations Using Our API