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ê pode encontrar na documentação da REST API da Braze.

Endpoints

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

Para encontrar seu endpoint REST na Braze:

1. Faça login na Braze e acesse Configurações > APIs e identificadores > Chaves de API.
2. Selecione uma chave de API existente ou selecione Criar chave de API para criar uma nova chave.
3. Copie o endpoint REST exibido nessa 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 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 frequência padrão de 250.000 solicitações por hora. No entanto, certos tipos de solicitação têm seu próprio limite de frequência aplicado para lidar melhor com altos volumes de dados na base de clientes. Para saber mais, consulte Limites de frequência da API

IDs de usuário

• ID de usuário externo: O external_id serve como um identificador único 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 múltiplos perfis para o mesmo usuário.
• ID de usuário Braze: O braze_id serve como um identificador único de usuário definido pela Braze. Você pode usar esse identificador para excluir usuários por meio da REST API, além dos external_ids.

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

Sobre as chaves da REST API

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

Espaços de trabalho e chaves de API andam lado a lado na Braze. Os espaços de trabalho são projetados para abrigar versões do mesmo app em múltiplas plataformas. Muitos clientes também usam espaços de trabalho para conter versões gratuitas e premium dos seus apps na mesma plataforma. Como você pode notar, esses espaços de trabalho também utilizam a REST API e possuem suas próprias chaves da REST API. Essas chaves podem ter escopo individual para incluir acesso a endpoints específicos da API. Cada chamada à API deve incluir uma chave com acesso ao endpoint utilizado.

Referimos tanto a chave da REST API quanto a chave da API do espaço de trabalho como api_key. A api_key é incluída em cada solicitação como cabeçalho da solicitação e funciona como uma chave de autenticação que permite utilizar nossas REST APIs. Essas REST APIs são usadas para rastrear usuários, enviar mensagens, exportar dados de usuários e muito mais. Ao criar uma nova chave da REST API, você deve conceder acesso a endpoints específicos. Atribuindo permissões específicas a uma chave de API, você pode limitar exatamente quais chamadas uma chave de API pode autenticar.

Dica

Além das chaves da REST API, existe também um tipo de chave chamado chaves de identificação, que pode ser usado para referenciar itens específicos como apps, modelos, Canvas, Campaigns, Content Cards e Segments na API. Para saber mais, consulte Tipos de identificadores de API.

Criando chaves da REST API

Para criar uma nova chave da REST API:

1. Acesse Configurações > APIs e identificadores.
2. Selecione Criar chave de API.
3. Dê um nome à sua nova chave para fácil identificação.
4. Especifique endereços IP permitidos e sub-redes para a nova chave.
5. Selecione quais permissões você deseja associar à nova chave.

Importante

Tenha em mente que, depois de criar uma nova chave de API, você não pode editar o escopo de permissões nem os IPs permitidos. Essa limitação existe por motivos de segurança. Se precisar alterar o escopo de uma chave, crie uma nova chave com as permissões atualizadas e implemente essa chave no lugar da antiga. Após concluir a implementação, você pode excluir a chave antiga.

Permissões de chaves da REST API

As permissões de chaves de API são permissões que você pode atribuir a um usuário ou grupo para limitar seu acesso a determinadas chamadas de API. Para visualizar sua lista de permissões de chaves de API, acesse Configurações > APIs e identificadores e selecione sua chave de API.

• dados de usuário
• e-mail
• mensagens
• campaigns
• canvas
• segments
• compras
• eventos
• sessões
• kpis
• modelos
• sso
• content blocks
• central de preferências
• inscrição
• sms
• catálogos
• autenticação do sdk

Gerenciando chaves da REST API

Você pode visualizar detalhes ou excluir chaves da REST API existentes em Configurações > APIs e identificadores > guia API Keys. Observe que não é possível editar chaves da REST API após criá-las.

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

Para ver os detalhes de uma chave de API, passe o mouse sobre a chave e selecione Visualizar. Isso inclui todas as permissões que essa chave possui, IPs na lista de permissões (se houver) e se essa chave está habilitada para a 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 esse usuário criou. Para excluir uma chave, passe o mouse sobre ela e selecione Excluir.

Segurança das chaves 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 conceder acesso a endpoints específicos. Atribuindo permissões específicas a uma chave de API, você pode limitar exatamente quais chamadas uma chave de API pode autenticar.

Considerando que as chaves da REST API permitem acesso a endpoints da REST API potencialmente sensíveis, 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 do seu website nem a exponha de qualquer outra forma pública.

Uma boa prática de segurança é conceder a um usuário apenas o nível de acesso necessário para realizar seu trabalho. Esse princípio também pode ser aplicado às chaves de API, atribuindo permissões a cada chave. Essas permissões oferecem maior segurança e controle sobre as diferentes áreas da sua conta.

Aviso

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

Se você expor uma chave acidentalmente, poderá excluí-la pelo Console de Desenvolvedor. Para obter 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 IPs permitidos da API

Para segurança adicional, você pode especificar uma lista de endereços IP e sub-redes que têm permissão para fazer solicitações à REST API para uma determinada chave da REST API. Isso é chamado de lista de permissões (allowlisting ou whitelisting). 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 fazendo um webhook Braze-to-Braze e usando lista de permissões, consulte a lista de IPs para incluir na lista de permissões.

Autenticação e segurança da API

Autenticação por token Bearer

A Braze autentica solicitações da REST API usando a chave da API REST passada como um token Bearer no cabeçalho de solicitação Authorization. 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 no lado do servidor:

1. Validade do token: Verifica se a chave da API REST existe na Braze e está ativa (por exemplo, não foi revogada ou desativada).
2. Autorização do token: Confirma que a chave de API possui 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, consulte Erros de API.

Capitalização do cabeçalho de solicitação

Os nomes dos cabeçalhos HTTP não diferenciam maiúsculas de minúsculas, então Authorization e authorization são equivalentes. O mesmo se aplica a outros cabeçalhos de solicitação padrão, como Content-Type. Envie a capitalização que seu cliente HTTP produzir.

A Braze também aceita qualquer capitalização do esquema Bearer (Bearer, bearer ou BEARER). Envie a chave da API REST exatamente como ela foi emitida.

Segurança em nível de rede

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

A criptografia TLS cobre todos os elos da cadeia. Seu servidor se conecta ao Cloudflare via TLS, e o Cloudflare estabelece uma conexão TLS separada através do NLB até o NGINX ingress, de modo que sua chave de API e os dados da solicitação permanecem criptografados em trânsito.

Recursos adicionais

Biblioteca cliente Ruby

Se você está implementando a Braze usando Ruby, pode usar a biblioteca cliente Ruby para reduzir o tempo de importação de dados. Uma biblioteca cliente é uma coleção de código específica para 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].