> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/pt/sonar/administration/settings/api-keys.md).

# Chaves de API

Crie chaves de API para scripts e integrações, vincule cada chave a um usuário cujo papel define o que ela pode fazer, defina uma validade para ela e revogue-a.

## O que é e quando usar

Uma chave de API permite que um script ou uma integração chame a API do SONAR sem um login interativo. Cada chave pertence a um usuário do console e age como esse usuário: tem as permissões do papel dele, e o **Client & Site Access** do papel se aplica a ela como se aplica ao usuário. Use uma chave para alimentar um CMDB com um inventário, para abrir chamados a partir de alertas, ou para executar um script em dispositivos a partir de um agendador externo.

As chaves são gerenciadas em **Admin Center › Settings**, na aba **API Keys**.

{% hint style="warning" %}
Uma chave se autentica sozinha, sem senha nem código de autenticador. Trate-a como uma senha: guarde-a em um cofre de segredos, nunca em um script que outras pessoas possam ler, e defina uma validade para ela.
{% endhint %}

## Antes de começar

* Para abrir **Admin Center › Settings**: a permissão **View Core Settings**.
* Para ver as chaves: **List API Keys**. Para criá-las, editá-las ou excluí-las: **Manage API Keys**.
* Para escolher o usuário da chave: **List Accounts**.
* Um usuário para a chave. Para uma integração, crie um usuário dedicado com um papel que conceda apenas o que a integração precisa, e marque **Block Dashboard Logins** nele para que não possa entrar no console. As chaves dele continuam funcionando. Veja [Usuários](https://wiki.datadike.com/pt/sonar/administration/identities/users.md).
* O endereço da API da sua instalação, fornecido com ela. Esta página o escreve como `https://api.example.com`.

## Passos

### Criar uma chave

1. Abra **Admin Center › Settings** e selecione a aba **API Keys**.
2. Clique em **Add key**. A caixa de diálogo **Add API Key** informa `API Key will be generated on save`.
3. Digite um **Name** que diga para que serve a chave, por exemplo `cmdb-sync`.
4. Escolha o **User** em nome do qual a chave age.
5. Opcional: defina **Key Expiration (Not required)**. Depois dessa data, a chave para de funcionar.
6. Clique em **Submit**.
7. Na lista, clique no ícone de cópia na linha da chave (**Copy API Key to clipboard**) e guarde a chave no seu cofre de segredos.

### Enviar a chave em cada requisição

Coloque a chave no cabeçalho `X-API-KEY` de todas as requisições:

```bash
curl -s \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  "https://api.example.com/agents/?page=1&page_size=10"
```

A requisição é executada com as permissões do usuário da chave. Veja [API](https://wiki.datadike.com/pt/sonar/reference/api.md) para os endpoints.

### Alterar uma chave

1. Clique duas vezes na linha da chave, ou clique nela com o botão direito e escolha **Edit**.
2. Altere **Name**, **User** ou **Key Expiration (Not required)**. O campo **Key** mostra a chave e não pode ser alterado.
3. Clique em **Submit**.

### Revogar uma chave

1. Clique com o botão direito na linha da chave e escolha **Delete**.
2. Confirme **Delete** na caixa de diálogo **Delete API key: ...?**.

A chave para de funcionar na hora. Para suspender todas as chaves de um usuário, desmarque **Active** no usuário, em **Admin Center › Users**. Excluir o usuário exclui as chaves dele.

## O que você deve ver

A chave aparece na lista com **Name**, **User**, **Expiration** e a data de **Created**. Mensagens confirmam cada ação: `The API Key was added`, `The API Key was edited`, `The API Key was deleted` e `Key was copied to clipboard!`.

## Como verificar se funcionou

1. Execute a chamada `curl` acima a partir da máquina que vai executar a integração. Uma chave válida retorna uma página JSON de dispositivos com `count`, `total_pages`, `next`, `previous` e `results`.
2. Faça uma alteração pela API, por exemplo edite a descrição de um dispositivo, e abra **Reports & Audits › Audits**. A entrada **Modify Object** traz o nome de usuário do usuário da chave.
3. Depois de excluir uma chave ou desativar o usuário dela, repita a chamada. Ela precisa falhar com o status 401.

## Erros comuns

| Sintoma                                                      | Causa                                                                                            | Correção                                                                |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| 401 com `Invalid token.`                                     | A chave está errada, incompleta ou foi excluída                                                  | Copie a chave de novo da lista, ou crie uma nova                        |
| 401 com `The token has expired.`                             | **Key Expiration** está no passado                                                               | Edite a chave e defina uma data posterior, ou limpe o campo             |
| 401 com `User inactive or deleted.`                          | O usuário da chave está desativado                                                               | Ative o usuário, ou passe a chave para um usuário ativo                 |
| 401 com `Authentication credentials were not provided.`      | O cabeçalho está ausente ou grafado errado                                                       | Envie a chave em `X-API-KEY`                                            |
| 403 com `You do not have permission to perform this action.` | O papel do usuário não tem a permissão, ou o dispositivo está fora dos clientes e sites do papel | Amplie o papel, ou use a chave de um usuário cujo papel cubra a chamada |
| `name: api key with this name already exists.`               | Os nomes das chaves são únicos                                                                   | Escolha outro nome                                                      |
| `name: Ensure this field has no more than 25 characters.`    | O nome tem mais de 25 caracteres                                                                 | Encurte-o                                                               |
| `user: This field is required.`                              | Nenhum usuário foi escolhido                                                                     | Escolha o **User**                                                      |

## Referência de campos

| Campo                         | O que faz                                                                                 | Valores aceitos                 | Padrão               |
| ----------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------- | -------------------- |
| Name                          | Identifica a chave na lista e na trilha de auditoria                                      | Texto, único, até 25 caracteres | (sem padrão)         |
| User                          | O usuário do console em nome do qual a chave age. A chave tem as permissões desse usuário | Qualquer usuário do console     | (sem padrão)         |
| Key                           | O segredo em si, gerado ao salvar                                                         | 32 caracteres, somente leitura  | Gerado               |
| Key Expiration (Not required) | Data e hora depois das quais a chave para de funcionar                                    | Uma data e hora, ou vazio       | Vazio (sem validade) |
| Created                       | Quando a chave foi criada                                                                 | Exibido na lista                | (sem padrão)         |

## Páginas relacionadas

* [API](https://wiki.datadike.com/pt/sonar/reference/api.md): endereço base, endpoints e erros
* [Usuários](https://wiki.datadike.com/pt/sonar/administration/identities/users.md): o usuário em nome do qual uma chave age, e **Block Dashboard Logins**
* [Papéis e permissões](https://wiki.datadike.com/pt/sonar/administration/identities/roles.md): o que o usuário da chave pode fazer
* [Trilha de auditoria](https://wiki.datadike.com/pt/sonar/administration/audit/audit-trail.md): as alterações feitas por meio de uma chave
