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ê usa 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 grandes volumes de dados na base de clientes. Para saber mais, consulte Limites de frequência da API

IDs de usuário

• 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 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 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 identificação do app para rastrear, acessar, enviar, exportar e analisar dados, ajudando a garantir que tudo funcione sem problemas.

Espaços de trabalho e chaves de API estão intimamente relacionados 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 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 da API. Cada chamada à API deve incluir uma chave com acesso ao endpoint chamado.

Referimo-nos 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 atua 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ê 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 identificação, que pode ser usado para referenciar coisas específicas 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ê um nome à sua nova chave para identificação rápida.
4. Especifique 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, não é possível 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 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 o acesso a determinadas chamadas de API. Para visualizar a lista de permissões de chaves de API, acesse Configurações > APIs e identificadores 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

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 visualizar os detalhes de uma chave de API, passe o mouse sobre a chave e selecione Visualizar. Isso inclui todas as permissões que a 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 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. Ao atribuir permissões específicas a uma chave de API, você pode limitar exatamente quais chamadas uma chave de API pode autenticar.

Dado 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 de confiança. Elas nunca devem ser expostas publicamente. Por exemplo, não use essa chave para fazer chamadas AJAX do seu website ou exponha-a de qualquer outra maneira 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 a chaves de API atribuindo permissões a cada chave. Essas permissões oferecem melhor segurança e controle sobre as diferentes áreas da sua conta.

Aviso

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

Se você expor uma chave acidentalmente, poderá 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 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 para 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 à 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-para-Braze e usando a 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 retornará 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 possui permissão para o endpoint solicitado. Para saber mais, consulte Erros de API.

Uso de maiúsculas e minúsculas no cabeçalho da solicitação

Os nomes dos cabeçalhos HTTP não diferenciam maiúsculas de minúsculas, portanto Authorization e authorization são equivalentes. O mesmo se aplica a outros cabeçalhos de solicitação padrão, como Content-Type. Envie o formato de 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 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 para a Braze:

A criptografia TLS cobre cada link da cadeia. Seu servidor se conecta ao Cloudflare por 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 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].