> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chaves de API

> Crie, delimite, monitore, alterne, suspenda, revogue e use chaves de API do CaseBender com segurança.

## 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

<Warning>
  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.
</Warning>

## 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

<Steps>
  <Step title="Abra Chaves de API">
    Acesse **Configurações → Conta → Chaves de API**.
  </Step>

  <Step title="Inicie a criação">
    Selecione **Criar chave de API**.
  </Step>

  <Step title="Descreva a chave">
    Informe um **Nome** claro e, opcionalmente, uma descrição que identifique a carga de trabalho, o responsável e a finalidade.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Crie e autentique">
    Selecione **Criar chave** e conclua a autenticação adicional quando solicitado.
  </Step>

  <Step title="Salve a credencial">
    Copie a chave completa de **Salve sua chave de API** para um gerenciador de segredos aprovado antes de selecionar **Concluído**.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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.

<Warning>
  Conceda `api-keys:write`, escopos curinga ou administrativos somente a automações confiáveis que estejam explicitamente autorizadas a criar ou gerenciar outras credenciais.
</Warning>

## 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

```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
  --header "Authorization: Bearer $CASEBENDER_API_KEY" \
  --header "Content-Type: application/json"
```

### Alternativa: X-Api-Key

```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
  --header "X-Api-Key: $CASEBENDER_API_KEY" \
  --header "Content-Type: application/json"
```

<Note>
  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.
</Note>

Consulte a [introdução da Referência da API](/pt-BR/api-reference/introduction) 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.

<Steps>
  <Step title="Prepare o consumidor">
    Confirme que você pode atualizar imediatamente o serviço consumidor e que possui um plano de reversão.
  </Step>

  <Step title="Alterne">
    Abra o menu de ações da chave e selecione **Alternar chave**.
  </Step>

  <Step title="Salve a nova chave">
    Copie a credencial recém-exibida para seu gerenciador de segredos.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  A alternância invalida o segredo anterior. Coordene a alteração para evitar uma interrupção da integração.
</Warning>

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.

<Warning>
  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.
</Warning>

## 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

* [Listar chaves de API](/en/api-reference/endpoint/api-keys/list)
* [Criar uma chave de API](/en/api-reference/endpoint/api-keys/create)
* [Listar escopos disponíveis](/en/api-reference/endpoint/api-keys/scopes)
* [Obter uma chave de API](/en/api-reference/endpoint/api-keys/get-by-id)
* [Alternar uma chave de API](/en/api-reference/endpoint/api-keys/rotate)
* [Visualizar estatísticas da chave de API](/en/api-reference/endpoint/api-keys/stats)
* [Excluir uma chave de API](/en/api-reference/endpoint/api-keys/delete)

## Guias relacionados

* [Introdução da Referência da API](/pt-BR/api-reference/introduction)
* [Controle de acesso](/en/security/access-control)
* [Organizações](./organizations.mdx)