Pular para o conteúdo principal

​
Visão geral

As chaves de API fornecem acesso programático ao CaseBender. Abra Configurações → Conta → Chaves de API para gerenciar as chaves disponíveis para sua conta e organização atual. A página oferece:
  • Pesquisa e filtros por status ou categoria
  • Identificadores de chave mascarados
  • Status, categoria, data do último uso e quantidade de requisições
  • Estatísticas de uso
  • Ações de ciclo de vida, como alternância, suspensão, revogação e exclusão
Uma chave de API é uma credencial. Armazene-a em um gerenciador de segredos aprovado, nunca a envie para o controle de versão e nunca a inclua em logs, capturas de tela, tíquetes ou mensagens de chat.

​
Pré-requisitos

  • Sua função deve permitir operações de gravação e o gerenciamento de chaves de API.
  • Os escopos disponíveis são filtrados de acordo com sua função.
  • A criação, revogação ou exclusão de uma chave pode exigir autenticação adicional.
  • Sua organização pode impor políticas adicionais de autenticação e acesso.
Funções somente leitura podem visualizar as informações permitidas, mas não podem alterar chaves.

​
Criar uma chave de API

1

Abra Chaves de API

Acesse Configurações → Conta → Chaves de API.
2

Inicie a criação

Selecione Criar chave de API.
3

Descreva a chave

Informe um Nome claro e, opcionalmente, uma descrição que identifique a carga de trabalho, o responsável e a finalidade.
4

Selecione uma categoria

Escolha a categoria adequada para o volume de requisições esperado da carga de trabalho. As categorias disponíveis vão de Básica a Ilimitada.
5

Defina uma validade

Se desejar, informe o número de dias até o vencimento. Para credenciais de produção, dê preferência a períodos curtos e alinhados à política.
6

Selecione os escopos

Escolha pelo menos um escopo. Use Selecionar todos somente quando a carga de trabalho realmente precisar de todos os escopos disponíveis para sua função.
7

Crie e autentique

Selecione Criar chave e conclua a autenticação adicional quando solicitado.
8

Salve a credencial

Copie a chave completa de Salve sua chave de API para um gerenciador de segredos aprovado antes de selecionar Concluído.
A chave completa é exibida apenas uma vez. O CaseBender armazena somente as informações necessárias para validá-la e identificá-la; a credencial em texto simples não poderá ser recuperada posteriormente.

​
Escolher escopos

Os escopos usam um padrão de recurso e ação, como cases:read ou organizations:*. As categorias de escopo podem incluir casos, alertas, tarefas, usuários, equipes, organizações, configurações e gerenciamento de chaves de API. Siga o princípio do privilégio mínimo:
  • Use escopos somente leitura para cargas de trabalho de relatórios e pesquisa.
  • Conceda escopos de gravação somente quando a integração realizar alterações.
  • Evite escopos curinga e administrativos para integrações de finalidade única.
  • Crie chaves separadas para serviços ou ambientes sem relação entre si.
  • Revise os requisitos de escopo sempre que uma integração mudar.
O formulário de criação em Configurações oferece somente os escopos permitidos por sua função atual. As requisições de API são avaliadas conforme os escopos da chave e os demais controles de dados aplicáveis.
Conceda api-keys:write, escopos curinga ou administrativos somente a automações confiáveis que estejam explicitamente autorizadas a criar ou gerenciar outras credenciais.

​
Escolher uma categoria

A categoria registra a classe de serviço pretendida para uma chave. As categorias disponíveis são:
  • Basic
  • Standard
  • Professional
  • Enterprise
  • Unlimited
Os limites efetivos de requisições, operações em lote e concorrência dependem da configuração da implantação. Valide a capacidade de produção e a aplicação dos limites com o administrador da plataforma, em vez de supor que a seleção de uma categoria altere os limites ativos ou torne uma chave irrestrita.

​
Autenticar requisições de API

Use a chave completa com um dos cabeçalhos compatíveis para chave única.

​
Recomendado: token Bearer

​
Alternativa: X-Api-Key

Armazene a chave em uma variável de ambiente ou em um mecanismo de injeção de segredos. Não cole uma chave real diretamente no histórico do shell nem no código-fonte.
Consulte a introdução da Referência da API para ver outros exemplos.

​
Entender os status das chaves

  • Chaves Ativas podem autenticar requisições, sujeitas às verificações de escopo e política.
  • Chaves Suspensas ficam temporariamente desabilitadas e podem ser reativadas.
  • Chaves Revogadas são permanentemente inválidas.
  • Chaves Expiradas ultrapassaram a validade configurada.

​
Visualizar estatísticas de uso

Abra o menu de ações de uma chave e selecione Visualizar estatísticas para consultar:
  • Total de requisições
  • Requisições bem-sucedidas
  • Requisições com falha
  • Tempo médio de resposta
  • Principais endpoints
Use essas estatísticas para identificar credenciais não utilizadas, endpoints inesperados e cargas de trabalho que exigem outra categoria.

​
Alternar uma chave

A alternância substitui o segredo atual por um novo.
1

Prepare o consumidor

Confirme que você pode atualizar imediatamente o serviço consumidor e que possui um plano de reversão.
2

Alterne

Abra o menu de ações da chave e selecione Alternar chave.
3

Salve a nova chave

Copie a credencial recém-exibida para seu gerenciador de segredos.
4

Atualize e verifique

Atualize a carga de trabalho consumidora, reinicie-a ou reimplante-a conforme necessário e faça uma requisição de teste com o escopo apropriado.
A alternância invalida o segredo anterior. Coordene a alteração para evitar uma interrupção da integração.
A alternância é iniciada pelo operador. Um intervalo de alternância armazenado não garante, por si só, que o CaseBender alternará e distribuirá automaticamente uma chave substituta.

​
Suspender ou reativar uma chave

Use Suspender para interromper temporariamente o uso de uma chave durante uma investigação ou manutenção planejada. Use Reativar somente após confirmar que a credencial e seu consumidor são confiáveis. A suspensão é preferível à exclusão quando você precisa de uma ação de contenção reversível.

​
Revogar uma chave

Use Revogar quando uma credencial estiver comprometida, deixar de ser confiável ou for desativada permanentemente. A revogação pode exigir autenticação adicional e não pode ser revertida. Após a revogação:
  1. Remova o segredo de todos os consumidores.
  2. Analise as estatísticas de uso e a telemetria de segurança.
  3. Investigue requisições inesperadas.
  4. Crie uma chave substituta separada somente se a carga de trabalho continuar autorizada.

​
Excluir uma chave

A exclusão remove o registro da chave e sua visibilidade direta de gerenciamento. Ela pode exigir autenticação adicional.
Revogue uma chave antes de excluí-la quando precisar de uma sequência clara de desativação da credencial. O menu de ações atual não apresenta uma caixa de diálogo de confirmação separada para todas as operações destrutivas.

​
Recomendações de segurança

  • Atribua um responsável humano nominal e um responsável pela carga de trabalho.
  • Use chaves separadas para produção, homologação e desenvolvimento.
  • Defina uma validade alinhada à sua política de credenciais.
  • Faça a alternância imediatamente após suspeita de exposição.
  • Monitore requisições com falha e endpoints inesperados.
  • Revogue chaves não utilizadas em vez de mantê-las ativas.
  • Nunca envie chaves por e-mail ou ferramentas de colaboração.

​
Solução de problemas

​
A criação da chave é rejeitada

Informe um nome, selecione pelo menos um escopo, confirme se sua função possui acesso de gravação e conclua qualquer desafio de autenticação adicional.

​
Uma requisição de API retorna 401

Confirme se a chave ativa completa foi fornecida como token Bearer ou X-Api-Key e verifique se ela não expirou, foi suspensa ou revogada.

​
Uma requisição de API retorna 403

A chave foi autenticada, mas não possui o escopo ou o acesso aos dados necessário. Adicione somente o escopo mínimo exigido por meio de um fluxo autorizado de gerenciamento de chaves.

​
As requisições têm a taxa limitada

Reduza a frequência das requisições, respeite as orientações de nova tentativa da resposta ou pergunte a um administrador se a carga de trabalho exige outra categoria.

​
A chave completa não está mais visível

Chaves em texto simples não podem ser recuperadas. Alterne a chave ou crie uma substituta e atualize o consumidor.

​
Referência da API

​
Guias relacionados