Braze Authentication: API Keys, Security, and Best Practices

Authentication overview

Braze employs a multi-faceted approach to authentication, designed to secure various types of interactions with its platform. For most server-side integrations, API Keys serve as the primary method, providing a straightforward mechanism for applications to access Braze APIs and manage customer data or trigger campaigns. These keys grant specific permissions, limiting potential exposure in case of compromise. For client-side interactions, such as those originating from mobile applications or web browsers, Braze's Software Development Kits (SDKs) handle authentication internally, often leveraging device-specific identifiers or secure tokens to ensure user sessions are properly managed without exposing sensitive API credentials directly. Additionally, for integrations requiring delegated authorization from users or third-party services, Braze supports the OAuth 2.0 framework, which is a widely adopted industry standard for secure authorization (OAuth 2.0 specification details).

The choice of authentication method depends on the nature of the integration and the level of access required. Server-to-server communications, such as those from a backend system pushing data to Braze or retrieving analytics, typically utilize API keys. Client-side applications, including those built with Braze's iOS, Android, and Web SDKs, rely on the SDK's built-in authentication mechanisms to securely communicate with Braze endpoints. OAuth 2.0 is generally reserved for scenarios where a user grants an application permission to access their Braze data or perform actions on their behalf without sharing their direct Braze credentials, such as a third-party analytics tool integrating with a Braze account.

Supported authentication methods

Braze supports several authentication methods to accommodate different integration patterns and security requirements. Understanding each method's purpose and security implications is essential for building robust and secure applications that interact with the Braze platform.

API Key Authentication

API Keys are unique alphanumeric strings that act as both an identifier and a secret token. When making a request to the Braze REST APIs, these keys are typically included in the HTTP request headers. Braze API Keys are often associated with specific workspaces and can be configured with granular permissions, allowing administrators to control which API endpoints and data types a given key can access (Braze API documentation). This granular control is a critical security feature, as it limits the potential impact if an API Key is compromised. For example, a key might be restricted to only send push notifications, preventing it from accessing user profiles or campaign analytics.

SDK Authentication

Braze provides SDKs for various platforms, including iOS, Android, Web, React Native, and Flutter. These SDKs abstract away much of the complexity of authenticating and interacting with Braze from client-side applications. Instead of requiring developers to manage API Keys directly within client code (which is generally insecure), the SDKs handle the secure establishment of communication channels. This often involves registering the application with Braze and configuring the SDK with an App Group ID or similar identifier, which then facilitates secure token exchange and session management behind the scenes. The SDKs are designed to protect sensitive information and ensure that data is transmitted securely to Braze endpoints.

OAuth 2.0 Authentication

OAuth 2.0 is an authorization framework that enables an application to obtain limited access to an HTTP service on behalf of a resource owner (RFC 6749 for OAuth 2.0). Braze supports OAuth 2.0 for specific integration scenarios, particularly when a third-party application needs to interact with a Braze account with the explicit consent of the account owner. This method involves a series of steps, including redirecting the user to Braze for authorization, obtaining an authorization code, and then exchanging that code for an access token. Access tokens are typically short-lived and scoped, meaning they grant specific permissions for a limited duration, enhancing security by reducing the window of opportunity for misuse if a token is intercepted.

Getting your credentials

The process for obtaining authentication credentials in Braze varies depending on the method you intend to use.

API Keys

1. Log in to Braze Dashboard: Access your Braze account through the administrative dashboard.
2. Navigate to Developer Console: Go to Settings > API Keys.
3. Create New API Key: Click on Create New API Key.
4. Configure Permissions: Assign the necessary permissions to the API key based on the specific API endpoints it will need to access. It is a best practice to apply the principle of least privilege, granting only the minimum required permissions.
5. Name and Save: Give your API key a descriptive name and save it. The key will be displayed once upon creation. Copy it immediately, as it may not be retrievable later.

For detailed steps on creating and managing API keys, refer to the Braze API Key management documentation.

SDK Configuration

For client-side applications using Braze SDKs, authentication is configured within the application code rather than by generating a separate key in the dashboard for each client. You typically need your Braze App Group ID and sometimes an API Key specifically configured for client-side usage (though the SDK often handles much of this). The Braze App Group ID can be found in your Braze dashboard under Settings > App Group Settings. Each SDK has specific initialization instructions:

• iOS/tvOS: Configure your Braze.plist file or programmatically initialize the SDK with your App Group ID.
• Android: Add your API Key and App Group ID to your braze.xml file or initialize within your application class.
• Web: Initialize the Web SDK with your App Group ID and other configuration options in your JavaScript code.

Consult the respective Braze SDK documentation for specific platform setup instructions.

OAuth 2.0 Client Setup

Setting up an OAuth 2.0 integration typically involves:

1. Registering an Application: Within your Braze dashboard or developer portal (if applicable for third-party integrations), you would register your application. This process usually provides you with a Client ID and Client Secret.
2. Defining Redirect URIs: Specify the authorized redirect URIs where Braze will send the authorization code after a user grants permission.
3. Implementing the Flow: Your application then implements the OAuth 2.0 authorization code flow, which involves directing users to Braze for consent, handling the callback with the authorization code, and exchanging it for an access token using your Client ID and Client Secret.

For specific details on implementing OAuth 2.0 with Braze, refer to the Braze OAuth 2.0 documentation.

Authenticated request example

Here's an example of how to make an authenticated request to the Braze REST API using an API Key. This Python example uses the requests library to send a POST request to the Braze Users Track endpoint, adding a custom event for a user. Replace YOUR_BRAZE_API_KEY and YOUR_BRAZE_REST_ENDPOINT with your actual credentials and endpoint.

import requests
import json

API_KEY = "YOUR_BRAZE_API_KEY"
BRAZE_REST_ENDPOINT = "YOUR_BRAZE_REST_ENDPOINT" # e.g., https://rest.iad-01.braze.com

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
    "api_key": API_KEY, # Some Braze endpoints might require API key in body, others in header
    "attributes": [
        {
            "external_id": "user123",
            "first_name": "John",
            "last_name": "Doe",
            "email": "[email protected]"
        }
    ],
    "events": [
        {
            "external_id": "user123",
            "app_id": "YOUR_APP_ID",
            "name": "product_viewed",
            "time": "2023-10-27T10:00:00Z",
            "properties": {
                "product_id": "SKU456",
                "category": "Electronics"
            }
        }
    ]
}

response = requests.post(
    f"{BRAZE_REST_ENDPOINT}/users/track",
    headers=headers,
    data=json.dumps(payload)
)

print(f"Status Code: {response.status_code}")
print(f"Response Body: {response.json()}")

Note that while the example includes the API key in both the header and the payload for demonstration purposes, the primary method for most Braze API calls is via the Authorization: Bearer header. Always consult the specific Braze API endpoint documentation for exact requirements.

Security best practices

Implementing strong security practices is critical when integrating with Braze to protect customer data and ensure the integrity of your marketing campaigns. Adhering to these guidelines helps mitigate risks associated with authentication credentials.

• Principle of Least Privilege: Always grant API Keys and OAuth tokens only the minimum necessary permissions required for their intended function. Avoid using a single, highly privileged key for all integrations. Regularly review and adjust permissions as needed.
• Secure Credential Storage: Never hardcode API Keys, Client Secrets, or other sensitive credentials directly into your application's source code. Instead, store them in environment variables, secure configuration files, or dedicated secret management services (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault). For client-side applications, ensure that API keys are not directly exposed and leverage SDK-provided secure mechanisms.
• Rotate Credentials Regularly: Implement a policy for regularly rotating API Keys and OAuth Client Secrets. This reduces the window of exposure if a credential is compromised.
• Monitor API Usage: Keep an eye on your Braze API usage logs for any unusual activity or excessive requests, which could indicate a compromised key or malicious activity.
• Use HTTPS/TLS: Always ensure all communications with Braze APIs use HTTPS (TLS). This encrypts data in transit, protecting credentials and sensitive customer information from eavesdropping. Braze APIs inherently enforce HTTPS.
• Error Handling and Logging: Implement robust error handling for API calls. Avoid logging sensitive information like API keys or full request payloads in plain text in your application logs.
• IP Whitelisting (where available): If Braze offers IP whitelisting for API access, configure it to allow requests only from your trusted server IP addresses. This adds an extra layer of security by restricting network access to your API keys.
• Understand SDK Security: When using Braze SDKs, familiarize yourself with their security implications and configuration options. Ensure you are using the latest versions to benefit from security patches and improvements.
• OAuth State Parameter: When implementing OAuth 2.0, always utilize the state parameter to protect against Cross-Site Request Forgery (CSRF) attacks. The state parameter should be a unique, unguessable value generated by your application for each authorization request and validated upon receiving the callback (OAuth 2.0 security considerations).