O senhor deve ser um Owner ou Admin para criar, clonar ou excluir uma chave de API privada.
O que você vai aprender
Saiba como criar uma chave de API privada, que é um identificador exclusivo usado para chamadas de API, bem como definir um escopo.
Tanto a chave privada de API quanto os escopos ajudam o senhor a proteger seus dados e os dados do cliente, limitando o que terceiros podem acessar.
Sobre a chave privada de API e escoposSobre a chave privada de API e escopos
Quando o senhor faz uma chamada de API, ela permite que um software se conecte a outro. Essa conexão permite que um software solicite, edite ou adicione informações ao outro.
Uma chave de API privada garante que essa solicitação tem as permissões corretas (ou seja, que veio de um usuário, conta ou programa autorizado). Pense nisso como uma chave de casa: ela permite que o senhor e sua família entrem, mas mantém todos os outros fora.
A inclusão de um escopo para uma chave privada de API adiciona outra camada de autorização, limitando o elemento específico que um terceiro pode acessar. Os escopos são semelhantes a uma chave de hotel, dando acesso apenas a determinadas áreas (como seu quarto ou a academia) e não a todo o edifício.
Tipos de escoposTipos de escopos
Ao criar uma chave de API privada, o senhor deve selecionar seu escopo. Em outras palavras, o senhor deve decidir se deseja que um terceiro o faça:
- Não ter acesso a um API ponto de extremidade.
- Visualizar todos os dados de um API ponto de extremidade, mas sem poder fazer alterações (também chamado de "read-only").
- Criar, excluir e fazer outras alterações em qualquer coisa associada a esse ponto de extremidade (também chamado de "acesso total" ou "acesso de gravação").
Por exemplo, digamos que o senhor queira adicionar o assinante a uma lista Klaviyo de um software de terceiros. Nesse caso, o senhor deve ter acesso total (gravação) ao API ponto de extremidade para lista, perfil e perfil de assinatura em massa. No entanto, o terceiro não precisa ter acesso a nenhum outro ponto de extremidade.
O senhor pode saber mais sobre a API doKlaviyo e ver os escopos disponíveis para cada ponto de extremidade no portal do desenvolvedor.
Antes de começarAntes de começar
Observe o seguinte:
- Depois de criar uma chave de API privada, o senhor não pode:
- Veja novamente a chave privada de API.
- Dica: salve com segurança a chave privada de API e anote para que deseja usá-la, por exemplo, em um gerenciador de senhas.
- Adicionar ou editar seus escopos.
- Se o senhor precisar alterar os escopos, a única opção é excluir a chave de API privada original e criar uma nova com o escopo correto.
- Veja novamente a chave privada de API.
- A chave privada de API tem acesso total por padrão.
Se o senhor não tiver certeza de quais API ponto de extremidade, escopos ou permissões precisa, entre em contato com um desenvolvedor ou alcance um Klaviyo parceiro para obter ajuda.
Criar uma chave de API privadaCriar uma chave de API privada
O senhor não poderá visualizar uma chave de API privada depois de criá-la. Em vez disso, o senhor deve tratar a chave privada de API como uma senha: apenas compartilhando essas chaves com pessoas em quem confia e guardando-as em um local seguro, como um cofre ou gerenciador de senhas.
- Clique no nome da sua organização no canto inferior esquerdo.
- Navegue até Settings.
- Clique em Chaves de API.
- Clique em Create Private API Key.
- Dê um nome à chave da API.
- Escolha o escopo que o senhor deseja fornecer à chave de API:
- Somente leitura
- Completo
- Personalizado
- Selecione Create.
Agora, quando o senhor compartilha uma chave de API privada, o terceiro só terá acesso às informações que o senhor definiu no escopo.
Usando consultasUsando consultas
As consultas são usadas em cenários avançados. Se o senhor ainda não estiver familiarizado com as consultas ou com a forma de usá-las, recomendamos que trabalhe com um desenvolvedor.
Incluir
Observe que, se o senhor tentar usar a consulta include
, terá de alterar o formato do que está listado acima.
Por exemplo, o endpoint de perfis é /api/profiles.
No entanto, se o senhor adicionar o parâmetro de consulta include(/api/profiles?include=list), o senhor também precisará de acesso list:read ou list:full, dependendo do tipo de chamada de API que estiver fazendo.
Escopos
Usando o parâmetro scopes
, o senhor pode criar um parâmetro de URL para preencher automaticamente o acesso ao escopo necessário para sua chave de API privada.
Na consulta de escopos, inclua uma lista separada por vírgulas dos escopos que o senhor deseja pré-selecionar.
Um exemplo de URL é:
https://www.klaviyo.com/create-private-api-key?scopes=campaigns:read,campaigns:write
Os escopos que o senhor pode usar nessa consulta são:
- Campanhas
- campanhas:leia,
- campanhas:escrever,
- Catálogos
- catálogos:ler,
- catálogos:write,
- Privacidade dos dados
- privacidade de dados: leia,
- data-privacy:write,
- Eventos
- eventos:leia,
- eventos:escrever,
- Fluxos
- fluxos: leia,
- fluxos: escrever,
- Lista
- list:read,
- list:write,
- Métricas
- métricas: ler,
- métricas: escrever,
- Perfis
- perfis:ler,
- perfis:escrever,
- Segmentos
- segmentos: leia,
- segmentos:escrever,
- Assinaturas
- subscriptions:read,
- subscriptions:write,
- Tags
- tags:read,
- tags:write,
- Modelos
- modelos:ler,
- template:write
Clonar uma chave de API privada
Com chaves de API privadas, a clonagem permite que o senhor crie uma nova chave com os mesmos escopos e permissões da chave original.
Observe que:
- A clonagem não gera a mesma chave que a chave de API privada original.
- O senhor não pode renomear uma chave de API clonada; ela tem o mesmo nome da chave original.
Para clonar uma chave de API privada:
- Navegue até a guia API keys (Chaves de API ).
- Clique no menu de três pontos ao lado da tecla que o senhor deseja clonar.
- Selecione Clone > Clone.
- Copie ou faça o download da nova chave privada de API e armazene-a em um local seguro.
- Certifique-se de excluir a chave antiga se ela não for mais necessária.
Recursos adicionais
- Veja nosso artigo sobre como começar a usar as APIs do Klaviyo.
- Confira mais documentos para desenvolvedores.
- Saiba mais sobre como manter sua conta segura.