REST API key overview

This reference article covers two of the three main types of keys you will see at Braze, the REST API Key or App Group API Key, referred to as the api_key, and the App Identifier Key, known as the app_id, as well as what these keys are, how they are used at Braze, their permissions and how to keep them secure.

In addition to these keys, there also exists a third type of key called Identifier Keys that can be used to reference specific things like templates, Canvases, campaigns, Content Cards, and segments from the API. Information on those API Identifier types/keys can be found here.

What is a REST API key/app group API key?

A REST Application Programming Interface key (REST API key) is a unique code that is passed into an API to authenticate the API call and identify the calling application or user. API access is done using HTTPS web requests to your company’s REST API endpoint. We use REST API keys at Braze in tandem with our App Identifier keys to track, access, send, export, and analyze data to help make sure everything is running smoothly on both your and our end.

App Groups and API Keys go hand in hand at Braze. App Groups are designed to house versions of the same application across multiple platforms. Many clients also use app groups to contain free and premium versions of their applications on the same platform. As you may notice, these app groups are also making use of the REST API and have their own REST API keys. These keys can be individually scoped to include access to specific endpoints on the API. Each call to the API must include a key with access to the endpoint hit.

We refer to both the REST API Key and App Group API Key as the api_key. The api_key is included in each request as a request header and acts as an authentication key that allows you to utilize our REST APIs. These REST APIs are used to track users, send messages, export user data, and more. When you create a new REST API Key, you will need to give it access to specific endpoints. By assigning specific permissions to an API Key, you can limit exactly which calls an API Key can authenticate.

Where can I find it?

Your API keys can always be found in the Braze dashboard in the Developer Console under Settings. At the top of this new page, you will find the REST API Keys section. Here you can view all of your available REST API/App Group API Keys, and create new API keys.

How can I use it?

Prior to April 2020, API keys would be included as a part of the API request body or within the request URL as a parameter. Braze now has updated the way in which we read API keys. API keys are now set with the HTTP Authorization request header, making your API keys more secure.

While the old way of passing API keys continues to work, after a period of time this will be permanently removed so we urge users to update API calls accordingly.

REST API key permissions

API key permissions are permissions you can assign a user or group to limit their access to certain API calls.

• User Data
• Email
• Messages
• Campaigns
• Canvas
• Segments
• Purchases
• Events
• News Feed
• Sessions
• KPIs
• Templates
• SSO
• Content Blocks
• Subscription

Please check Braze documentation site or our Braze Postman documentation for a full description of these API endpoints.

The App Identifier API key

The App Identifier API key or app_id is a parameter associating activity with a specific app in your app group. It designates which app within the app group you are interacting with. For example, you will find that you will have an app_id for your iOS app, an app_id for your android app, and an app_id for your web integration. At Braze, you might find that you have multiple apps for the same platform across the various platform types that Braze supports.

App identifiers at Braze are used when integrating the SDK and are also used to reference a specific app in REST API calls. With the app_id you can do many things like pull data for a custom event that occurred for a particular app, retrieve uninstall stats, new user stats, DAU stats, and session start stats for a particular app.

Sometimes, you may find you are prompted for an app_id but you are not working with an app, because it is a legacy field specific to a specific platform, you can “omit” this field by including any string of characters as a placeholder for this required parameter.

Where can I find it?

There are two ways to locate your app_id:

1. You can find this app_id or application identifier in the Developer Console under Settings. On this new page, under Identification, you will be able to see every app_id that exists for your apps.

2. Go to Manage Settings under Settings. From this new page, in the Settings tab, midway through the page you will find an “API key for APP NAME on PLATFORM” (e.g “API Key for Ice Cream on iOS). This API key is your Application Identifier.

Multiple App Identifier API keys

During SDK set up, the most common use case for multiple App Identifier API keys is separating those keys for debug and release build variants. To easily switch between multiple App Identifier API keys in your builds, we recommend creating a separate braze.xml file for each relevant build variant. A build variant is a combination of build type and product flavor. Note that by default, a new Android project is configured with debug and release build types and no product flavors.

For each relevant build variant, create a new braze.xml for it in src/<build variant name>/res/values/:

1
2
3
4
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="com_appboy_api_key">REPLACE_WITH_YOUR_BUILD_VARIANT_API_KEY</string>
</resources>

When the build variant is compiled, it will use the new API key.

REST API key security

Security is of the utmost importance at Braze. Given that REST API Keys allow access to potentially sensitive REST API endpoints, please secure these keys and only share them with trusted partners. They should never be publicly exposed. For example, do not use this key to make AJAX calls from your website or expose it in any other public manner.

A good security practice is to assign a user only as much access as is necessary to complete their job: this principle can also be applied to API Keys by assigning permissions to each key. These permissions give you better security and control over the different areas of your account.

With App identifiers, the app_id is assigned by Braze and permissions cannot be assigned or revoked. Because of the nature of the relationship between app_id and the SDK, keeping this identifier secure is crucial in the security of your application.