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 está 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 para a 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 possui um limite de frequência padrão de 250.000 solicitações por hora. No entanto, determinados tipos de solicitação possuem seu próprio limite de frequência aplicado para lidar melhor com grandes volumes de dados na base de clientes. Para saber mais, consulte Limites de frequência da API

IDs de usuários

• ID externo do usuário: 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 múltiplos perfis para o mesmo usuário.
• ID de usuário Braze: O braze_id serve como um identificador exclusivo 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 de aplicativos REST) é um código exclusivo que você passa para uma API a fim de autenticar a chamada de API e identificar o aplicativo ou usuário que faz a chamada. Você acessa a API usando solicitações web HTTPS no endpoint da REST API da sua empresa. As chaves da REST API funcionam em conjunto com as chaves de identificação 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 caminham juntos na Braze. Os espaços de trabalho foram 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 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 escopos individuais definidos para incluir acesso a endpoints específicos da API. Cada chamada à API deve incluir uma chave com acesso ao endpoint chamado.

Nós 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. Ao criar uma nova chave da REST API, você 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 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 — a partir da 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ê à sua nova chave um nome para identificação rápida.
4. Especifique os endereços IP na lista de permissões e sub-redes para a nova chave.
5. Selecione quais permissões você deseja associar à sua nova chave.

Importante

Tenha em mente que, após criar uma nova chave de API, você não poderá editar o escopo de permissões ou os IPs na lista de permissões. 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-a no lugar da antiga. Após concluir a implementação, você poderá excluir a chave antiga.

Permissões da chave da REST API

As permissões da chave de API são permissões que você pode atribuir a um usuário ou grupo para limitar o acesso deles 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 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 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 cursor 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 cursor 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. Ao criar uma nova chave da REST API, você precisa 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 de API pode autenticar.

Considerando que as chaves da REST API permitem acesso a endpoints potencialmente sensíveis da REST API, 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 nenhuma outra forma pública.

Uma boa prática de segurança é atribuir a um usuário apenas o acesso necessário para realizar seu trabalho: esse princípio também pode ser aplicado a 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 potencialmente sensíveis da REST API, 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 nenhuma outra forma pública.

Se você acidentalmente expor uma chave, poderá excluí-la do 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 possuem perfis de segurança diferentes.

Lista de permissões de IP da API

Para segurança adicional, você pode especificar uma lista de endereços IP e sub-redes com permissão para fazer solicitações da REST API para uma determinada chave da REST API. Isso é chamado de lista de permissões (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 criando um webhook Braze-para-Braze e usando 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 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 executa 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 desabilitada).
2. Autorização do token: confirma se a chave de 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, consulte Erros de API.

Casing do cabeçalho de 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 o casing que seu cliente HTTP produzir.

A Braze também aceita qualquer casing 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 de 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 ingress NGINX, de modo que sua chave de API e os dados da solicitação permanecem criptografados em trânsito.

Recursos adicionais

Biblioteca de cliente Ruby

Se você está implementando a Braze usando Ruby, pode usar a biblioteca de cliente Ruby para reduzir o tempo de importação de dados. Uma biblioteca de 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 de cliente Ruby é compatível com os endpoints de usuário.

Importante

Esta biblioteca de cliente está em beta. Para ajudar a melhorá-la, envie feedback para [email protected].