API overview

This reference article covers the API basics, including common terminology and an overview of REST API keys, permissions, and how to keep them secure.

Braze REST API collection

API definitions

The following is an overview of terms you may see in the Braze REST API documentation.

Endpoints

Braze manages a number of different instances for our dashboard and REST endpoints. When your account is provisioned, you log in to one of the following URLs. Use the correct REST endpoint based on which instance you are provisioned to. If you are unsure, open a support ticket or use the following table to match the URL of the dashboard you use to the correct REST Endpoint.

To find your REST endpoint in Braze:

1. Log in to Braze and go to Settings > APIs and Identifiers > API Keys.
2. Select an existing API key, or select Create API Key to make a new key.
3. Copy the REST endpoint shown on this tab and use that endpoint for your API requests.

important

When using endpoints for API calls, use the REST endpoint.

For SDK integration, use the SDK endpoint, not the REST endpoint.

API limits

For most APIs, Braze has a default rate limit of 250,000 requests per hour. However, certain request types have their own rate limit applied to better handle high volumes of data across the customer base. For details, refer to API rate limits

User IDs

• External user ID: The external_id serves as a unique user identifier for whom you are submitting data. This identifier should be the same as the one you set in the Braze SDK in order to avoid creating multiple profiles for the same user.
• Braze user ID: braze_id serves as a unique user identifier that Braze sets. You can use this identifier to delete users through the REST API in addition to external_ids.

For more information, refer to the following articles based on your platform: iOS, Android, and Web.

About REST API keys

A REST Application Programming Interface key (REST API key) is a unique code that you pass into an API to authenticate the API call and identify the calling application or user. You access the API using HTTPS web requests to your company’s REST API endpoint. REST API keys work in tandem with App Identifier keys to track, access, send, export, and analyze data to help ensure everything is running smoothly.

Workspaces and API keys go hand in hand at Braze. Workspaces are designed to house versions of the same application across multiple platforms. Many customers also use workspaces to contain free and premium versions of their applications on the same platform. As you may notice, these workspaces 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 workspace 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 use 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 must 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.

tip

In addition to REST API keys, there also exists a type of key called Identifier keys that can be used to reference specific things like apps, templates, Canvases, campaigns, Content Cards, and segments from the API. For more information, refer to API identifier types.

Creating REST API keys

To create a new REST API key:

1. Go to Settings > APIs and Identifiers.
2. Select Create API Key.
3. Give your new key a name for identification at a glance.
4. Specify allowlisted IP addresses and subnets for the new key.
5. Select which permissions you want to be associated with your new key.

important

Keep in mind that after you create a new API key, you cannot edit the scope of permissions or the allowlisted IPs. This limitation is in place for security reasons. If you need to change the scope of a key, create a new key with the updated permissions and implement that key in place of the old one. After you’ve completed your implementation, you can delete the old key.

REST API key permissions

API key permissions are permissions you can assign a user or group to limit their access to certain API calls. To view your list of API key permissions, go to Settings > APIs and Identifiers, and select your API key.

• user data
• email
• messages
• campaigns
• canvas
• segments
• purchases
• events
• sessions
• kpis
• templates
• sso
• content blocks
• preference center
• subscription
• sms
• catalogs
• sdk authentication

Managing REST API keys

You can view details for or delete existing REST API keys from Settings > APIs and Identifiers > API Keys tab. Note that you cannot edit REST API keys after you create them.

The API Keys tab includes the following information for each key:

To view the details of an API key, hover over the key and select View. This includes all the permissions this key has, whitelisted IPs (if any), and if this key is opted into Braze IP whitelisting.

Note when deleting a user, Braze does not delete the associated API keys that user created. To delete a key, hover over the key and select Delete.

REST API key security

API keys are used to authenticate an API call. When you create a new REST API key, you 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.

Given that REST API keys allow access to potentially sensitive REST API endpoints, 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.

warning

Given that REST API keys allow access to potentially sensitive REST API endpoints, make sure they are stored and used securely. For example, do not use this key to make AJAX calls from your website or expose it in any other public manner.

If you accidentally expose a key, you can delete it from the Developer Console. For help with this process, open a support ticket.

Security of REST API keys and SDK API keys

REST API keys and SDK API keys have different security profiles.

API IP allowlisting

For additional security, you can specify a list of IP addresses and subnets which are allowed to make REST API requests for a given REST API key. This is referred to as allowlisting, or whitelisting. To allow specific IP addresses or subnets, add them to the Whitelist IPs section when creating a new REST API key:

If you don’t specify any, requests can be sent from any IP address.

tip

If you’re making a Braze-to-Braze webhook and using allowlisting, see the list of IPs to whitelist.

API authentication and security

Bearer token authentication

Braze authenticates REST API requests using the REST API key passed as a Bearer token in the Authorization request header. When you send a request, include your API key in the following format:

1
Authorization: Bearer YOUR_REST_API_KEY

On each request, Braze performs the following server-side validation checks:

1. Token validity: Verifies that the REST API key exists in Braze and is active (for example, not revoked or disabled).
2. Token authorization: Confirms the API key has the required permissions for the requested endpoint.

If authentication fails, the API returns an error response with an HTTP status code. For example, 401 Unauthorized indicates an invalid or missing key, while 403 Forbidden indicates the key doesn’t have permission for the requested endpoint. For more information, see API errors.

Network-level security

REST API requests to Braze are protected by Transport Layer Security (TLS) encryption across the full request path. The following table describes the network flow for an API request from your server to Braze:

TLS encryption covers every link in the chain. Your server connects to Cloudflare over TLS, and Cloudflare establishes a separate TLS connection through the NLB to the NGINX ingress, so your API key and request data remain encrypted in transit.

Additional resources

Ruby client library

If you’re implementing Braze using Ruby, you can use the Ruby client library to reduce your data import time. A client library is a collection of code specific to one programming language—in this case, Ruby—that makes it easier to use an API.

The Ruby client library supports the User endpoints.

important

This client library is in beta. To help make this library better, send feedback to [email protected].