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 seguintes URLs. Use o endpoint REST correto com base na instância à qual você foi 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 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 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, determinados tipos de solicitação têm seu próprio limite de frequência aplicado para lidar melhor com grandes volumes de dados em toda a 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 funciona como um identificador único de usuário para quem 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 funciona 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 seguintes artigos 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 exclusivo que você passa para uma API para autenticar a chamada de API e identificar o aplicativo ou usuário que está fazendo a chamada. Você acessa a API usando solicitações web HTTPS para o endpoint da REST API da sua empresa. As chaves da REST API funcionam em conjunto com as chaves de identificador do app para rastrear, acessar, enviar, exportar e analisar dados, garantindo que tudo funcione corretamente.

Os espaços de trabalho e as chaves de API andam juntos 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 de seus aplicativos na mesma plataforma. Como você pode perceber, esses espaços de trabalho também utilizam a REST API e possuem suas próprias chaves da REST API. Essas chaves podem ter escopos individuais para incluir acesso a endpoints específicos na API. Cada chamada à API deve incluir uma chave com acesso ao endpoint requisitado.

Nos referimos tanto à chave da REST API quanto à chave de API do espaço de trabalho como api_key. A api_key é incluída em cada solicitação como um cabeçalho da solicitação e funciona como uma chave de autenticação que permite o uso das 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, precisa conceder acesso a endpoints específicos. Ao atribuir 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, 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 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 identificação rápida.
4. Especifique os endereços IP permitidos e sub-redes para a nova chave.
5. Selecione quais permissões você deseja associar à sua nova chave.

Importante

Lembre-se de que, após criar uma nova chave de API, você não pode editar o escopo de 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. Após concluir a implementação, você pode excluir a chave antiga.

Permissões de chave da REST API

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

• dados do 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 Chaves de API. Observe que não é possível editar chaves da REST API após criá-las.

A guia Chaves de API 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 Visualizar. Isso inclui todas as permissões que esta chave possui, IPs na lista de permissões (se houver) e se esta 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 a chave e selecione Excluir.

Segurança da chave da REST API

As chaves de API são usadas para autenticar uma chamada de API. Quando você cria uma nova chave da REST API, precisa conceder acesso a endpoints específicos. Ao atribuir 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 site nem a exponha de qualquer outra forma pública.

Uma boa prática de segurança é conceder ao usuário apenas o 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 proporcionam melhor 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 utilizadas de forma segura. Por exemplo, não use essa chave para fazer chamadas AJAX do seu site nem a exponha de qualquer outra forma pública.

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

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

As chaves da REST API e as chaves de API do SDK possuem perfis de segurança diferentes.

Lista de permissões de IP para 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 é conhecido como 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-para-Braze e usando a lista de permissões, consulte a lista de IPs para adicionar à lista de permissões.

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 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 se 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 da solicitação

Os nomes de 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 foi emitida.

Segurança no 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 de uma solicitação de API do seu servidor para 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 melhorá-la, envie feedback para [email protected].