Visão geral da API

Este artigo de referência aborda os conceitos básicos da API, incluindo a terminologia comum e uma visão geral das chaves da REST API, permissões e como mantê-las seguras.

Coleção da REST API da Braze

Definições da API

A seguir, uma visão geral dos termos que você poderá encontrar na documentação da REST API da Braze.

Endpoints

A Braze gerencia várias instâncias diferentes para nosso dashboard e endpoints REST. Quando sua conta for provisionada, você faz login em uma das seguintes URLs. Use o endpoint REST correto com base na instância para a qual você está provisionado. Se você não tiver certeza, abra um ticket de suporte ou use a tabela a seguir para corresponder a URL do dashboard que você usa ao endpoint REST correto.

Para encontrar seu endpoint REST na Braze:

1. Faça login na Braze e acesse Settings > APIs and Identifiers > API Keys.
2. Selecione uma chave de API existente ou selecione Create API Key para criar uma nova chave.
3. Copie o endpoint REST mostrado nesta guia e use esse endpoint para suas solicitações de API.

Importante

Ao usar endpoints para chamadas de API, use o endpoint REST.

Para integração de SDK, use o endpoint de SDK, não o endpoint REST.

Limites da API

Para a maioria das APIs, a Braze tem um limite de taxa padrão de 250.000 solicitações por hora. No entanto, certos tipos de solicitações têm seu próprio limite de taxa aplicado para lidar melhor com altos volumes de dados em toda a base de clientes. Para mais informações, consulte Limites de taxa da API.

IDs de usuário

• ID externo: O external_id serve como um identificador exclusivo do usuário para o qual você está enviando dados. Esse identificador deve ser o mesmo que você definiu no SDK da Braze para evitar a criação de vários perfis para o mesmo usuário.
• ID do usuário da Braze: O braze_id serve como um identificador único de usuário definido pela Braze. Você pode usar esse identificador para excluir usuários pela REST API, além dos external_ids.

Para saber mais, consulte os seguintes artigos com base na sua plataforma: iOS, Android e Web.

Sobre as chaves da REST API

Uma chave de interface de programação de aplicativo REST (chave da REST API) é um código único que você passa para uma API para autenticar a chamada e identificar o aplicativo ou usuário que está fazendo a chamada. Você acessa a API usando solicitações web HTTPS para o endpoint REST da sua empresa. As chaves da REST API funcionam em conjunto com as chaves de identificador de app para rastrear, acessar, enviar, exportar e analisar dados, ajudando a garantir que tudo funcione sem problemas.

Os espaços de trabalho e as chaves de API andam de mãos dadas na Braze. Os espaços de trabalho são projetados para abrigar versões do mesmo aplicativo em várias plataformas. Muitos clientes também usam espaços de trabalho para conter versões gratuitas e premium dos seus aplicativos na mesma plataforma. Como você pode notar, esses espaços de trabalho também usam a REST API e têm suas próprias chaves da REST API. Essas chaves podem ter escopo individual para incluir acesso a endpoints específicos na API. Cada chamada para a API precisa incluir uma chave com acesso ao endpoint utilizado.

Referimo-nos tanto à chave da REST API quanto à chave da API do espaço de trabalho como api_key. O api_key é incluído em cada solicitação como um cabeçalho de solicitação e atua como uma chave de autenticação que permite usar nossas REST APIs. Essas REST APIs são usadas para rastrear usuários, enviar mensagens, exportar dados de usuários e muito mais. Quando você cria uma nova chave da REST API, deve conceder acesso a endpoints específicos. Ao atribuir permissões específicas a uma chave de API, você pode limitar exatamente quais chamadas essa chave pode autenticar.

Dica

Além das chaves da REST API, também existe um tipo de chave chamado chaves de identificador que pode ser usado para fazer referência a itens específicos, como apps, modelos, Canvas, Campaigns, Content Cards e Segments da API. Para saber mais, consulte Tipos de identificadores da API.

Criação de chaves da REST API

Para criar uma nova chave da REST API:

1. Acesse Settings > APIs and Identifiers.
2. Selecione Create API Key.
3. Dê um nome à sua nova chave para identificá-la rapidamente.
4. Especifique endereços IP na lista de permissões e sub-redes para a nova chave.
5. Selecione as permissões que deseja associar à sua nova chave.

Importante

Lembre-se: depois de criar uma nova chave de API, você não poderá editar o escopo das permissões ou os IPs permitidos. Essa limitação existe por motivos de segurança. Se você precisar alterar o escopo de uma chave, crie uma nova chave com as permissões atualizadas e implemente essa chave no lugar da antiga. Depois de concluir a implementação, você pode excluir a chave antiga.

Permissões de chave da REST API

As permissões de chave de API são permissões que podem ser atribuídas a um usuário ou grupo para limitar seu acesso a determinadas chamadas de API. Para visualizar sua lista de permissões de chave de API, acesse Settings > APIs and Identifiers e selecione sua chave de API.

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

Gerenciamento de chaves da REST API

Você pode visualizar detalhes ou excluir chaves da REST API existentes na guia Settings > APIs and Identifiers > API Keys. Observe que não é possível editar as chaves da REST API depois de criá-las.

A guia API Keys inclui as seguintes informações para cada chave:

Para visualizar os detalhes de uma chave de API, passe o mouse sobre a chave e selecione View. Isso inclui todas as permissões dessa chave, IPs na lista de permissões (se houver) e se essa chave está incluída na lista de permissões de IP da Braze.

Observe que ao excluir um usuário, a Braze não exclui as chaves de API associadas que o usuário criou. Para excluir uma chave, passe o mouse sobre ela e selecione Delete.

Segurança da chave da REST API

As chaves de API são usadas para autenticar uma chamada de API. Ao criar uma nova chave da REST API, você precisa dar a ela acesso a endpoints específicos. Ao atribuir permissões específicas a uma chave de API, você pode limitar exatamente quais chamadas essa chave pode autenticar.

Como as chaves da REST API permitem o acesso a endpoints da REST API potencialmente confidenciais, proteja essas chaves e compartilhe-as apenas com parceiros confiáveis. Elas nunca devem ser expostas publicamente. Por exemplo, não use essa chave para fazer chamadas AJAX no seu site nem a exponha de qualquer outra forma pública.

Uma boa prática de segurança é atribuir a um usuário apenas o acesso necessário para concluir seu trabalho: esse princípio também pode ser aplicado às chaves de API atribuindo permissões a cada chave. Essas permissões proporcionam mais segurança e controle sobre as diferentes áreas da sua conta.

Aviso

Como as chaves da REST API permitem o acesso a endpoints da REST API potencialmente confidenciais, certifique-se de que elas sejam armazenadas e usadas com segurança. Por exemplo, não use essa chave para fazer chamadas AJAX no seu site nem a exponha de qualquer outra forma pública.

Se você expuser acidentalmente uma chave, pode excluí-la no console de desenvolvedor. Para ajuda com esse processo, abra um ticket de suporte.

Segurança das chaves da REST API e das chaves da API SDK

As chaves da REST API e as chaves da API SDK têm perfis de segurança diferentes.

Lista de permissões de IP da API

Para maior segurança, você pode especificar uma lista de endereços IP e sub-redes que têm permissão para fazer solicitações de REST API para uma determinada chave da REST API. Isso é chamado de lista de permissões. Para permitir endereços IP ou sub-redes específicos, adicione-os à seção Whitelist IPs ao criar uma nova chave da REST API:

Se você não especificar nenhum, as solicitações poderão ser enviadas de qualquer endereço IP.

Dica

Se você estiver criando um webhook da Braze para a Braze e usando lista de permissões, veja a lista de IPs a serem permitidos.

Autenticação e segurança da API

Autenticação por token Bearer

A Braze autentica as solicitações da REST API usando a chave da REST API passada como um token Bearer no cabeçalho Authorization da solicitação. Ao enviar uma solicitação, inclua sua chave de API no seguinte formato:

1
Authorization: Bearer YOUR_REST_API_KEY

Em cada solicitação, a Braze realiza as seguintes verificações de validação do lado do servidor:

1. Validade do token: Verifica se a chave da REST API existe na Braze e está ativa (por exemplo, não revogada ou desativada).
2. Autorização do token: Confirma se a chave da API tem as permissões necessárias para o endpoint solicitado.

Se a autenticação falhar, a API retorna uma resposta de erro com um código de status HTTP. Por exemplo, 401 Unauthorized indica uma chave inválida ou ausente, enquanto 403 Forbidden indica que a chave não tem permissão para o endpoint solicitado. Para saber mais, veja Erros da API.

Segurança em nível de rede

As solicitações da REST API para a Braze são protegidas por criptografia TLS (Transport Layer Security) ao longo de todo o caminho da solicitação. A tabela a seguir descreve o fluxo de rede para uma solicitação de API do seu servidor para a Braze:

A criptografia TLS cobre cada elo da cadeia. Seu servidor se conecta ao Cloudflare via TLS, e o Cloudflare estabelece uma conexão TLS separada através do NLB para o ingress NGINX, garantindo que sua chave de API e os dados da solicitação permaneçam criptografados em trânsito.

Recursos adicionais

Biblioteca de cliente Ruby

Se você estiver implementando a Braze usando Ruby, pode usar a biblioteca cliente Ruby para reduzir o tempo de importação de dados. Uma biblioteca de cliente é uma coleção de códigos específicos de uma linguagem de programação — neste caso, Ruby — que facilita o uso de uma API.

A biblioteca cliente Ruby é compatível com os endpoints de usuário.

Importante

Esta biblioteca cliente está em beta. Para ajudar a melhorar esta biblioteca, envie feedback para [email protected].