# Consumers (Chaves de API)

Dentro da Digibee Integration Platform, um *Consumer* é uma entidade nominal que pode ser associada com Chaves de API ou um *Basic Auth*. Quando você cria um *Consumer*, uma Chave de API é gerada automaticamente.

Chaves de API são credenciais de acesso para consultas em *pipelines* usando *triggers* [REST](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/triggers/web-protocols/rest), [HTTP](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/triggers/web-protocols/http) e [HTTP File](https://app.gitbook.com/s/SKBJ6ZiEWBU93x170HH4/triggers/web-protocols/http-file). O uso de Chaves de API é necessário como garantia mínima de segurança. Um *Consumer* pode conter uma ou várias Chaves de API.

*Basic* Auth é um método de autenticação para os *triggers* REST, HTTP e HTTP File. Essa opção garante acesso somente para usuários que tenham um nome de usuário e senha registrados. Um *Consumer* pode conter uma ou mais credenciais *Basic Auth*.

Os *Consumers*, Chaves de API e *Basic Auth* relacionados a seu *pipeline* podem ser encontrados na página **Consumers (Chaves de API)**, que está estruturada da seguinte forma:

* Uma lista com o nome do *Consumer*.
* O número de *pipelines* associados.
* O número de Chaves de API relacionadas.
* O número de credenciais *Basic Auth* relacionadas.
* Dois ícones com opções de edição e remoção.

Você também pode procurar por um *Consumer*/Chave de API específico no campo de busca localizado acima da lista.

<figure><img src="https://content.gitbook.com/content/cO0A6g1dOsu8BiHYqO67/blobs/r3QAN8Yv2bdPTtjWIHNt/consumers-pagina.png" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Importante:** o uso de Chaves de API é obrigatório para chamar um *pipeline*. No entanto, você também pode usar o Basic Auth como uma camada adicional de segurança.
{% endhint %}

## **Como criar um Consumer**

1. Acesse o menu **Configurações**.
2. Clique em **Consumers (Chaves de API)**.
3. Selecione o ambiente (*test* ou *prod*) e clique em **Criar**. Uma nova tela irá aparecer.
4. Defina o nome e a descrição para o *Consumer*, e então clique no símbolo de “+” para associar *pipelines*.
5. Selecione o projeto e os *pipelines* que irão usar o Consumer e a Chave de API associada. Clique em **Confirmar** para validar a configuração.

## **Opções de edição**

O *Consumer* gerado aparece ao final da lista. Ao clicar no ícone do lápis, você pode acessar as seguintes opções de edição:

* Visualizar, copiar e remover as Chaves de API associadas clicando nos respectivos ícones.
* Adicionar uma nova Chave de API (saiba mais na seção abaixo).
* Configurar uma Chave de API para novos *pipelines*.
* Editar a lista de *pipelines* que usam a Chave de API.

## **Como criar uma Chave de API**

1. Acesse o menu **Configurações**.
2. Clique em ***Consumers*****&#x20;(Chaves de API)**.
3. Selecione o ambiente (*test* ou *prod*) e clique no ícone do lápis do *Consumer* desejado. Uma nova tela irá aparecer.
4. Selecione a aba **Chaves de API** e clique em **Adicionar Chave de API**.

<figure><img src="https://content.gitbook.com/content/cO0A6g1dOsu8BiHYqO67/blobs/00fp2j0aUrzq52tPp2Pe/consumers-chave-de-api.gif" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Importante**: crie uma Chave de API diferente para cada sistema consumidor da sua API para restringir acesso apenas para os *pipelines* desejados. Além das Chaves de API, também é recomendado usar JWT (*JSON Web Token*) para aumentar a segurança.
{% endhint %}

## **Como criar uma credencial Basic Auth**

1. Acesse o menu **Configurações**.
2. Clique em ***Consumers*****&#x20;(Chaves de API)**.
3. Selecione o ambiente (*test* ou *prod*) e clique no ícone do lápis do *Consumer* desejado. Uma nova tela irá aparecer.
4. Selecione a a aba **Basic Auth**, defina um nome de usuário e senha, e em seguida clique em **Adicionar Basic Auth**. Lembre-se que o nome de usuário não deve ser repetido.

<figure><img src="https://content.gitbook.com/content/cO0A6g1dOsu8BiHYqO67/blobs/jQti4edbzTKNa8ZUgfld/consumers-basic-auth-pt.gif" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Importante:** ao configurar uma credencial *Basic Auth*, o nome de usuário sempre recebe o prefixo {realm}, que faz referência ao *realm* do cliente. Exemplo: **{realm}-{username}**.
{% endhint %}

## **Como usar Chaves de API e Basic Auth em requisições direcionadas para o pipeline exposto**

Siga esses passos para usar uma Chave de API:

1. Acesse o *header* e defina o valor da chave para o parâmetro *apikey*. Também é necessário especificar o *Content-Type* esperado pelo *pipeline* (exemplo: application/json):
2. Caso não seja possível mudar o *header* da chamada no sistema legado, você pode incluir a Chave de API como um parâmetro de chamada na URL. No entanto, essa não é uma opção segura para serviços expostos. Nesse caso, certifique-se de que apenas serviços autorizados possam chamar a API exposta pela Digibee (controle de *Consumers*).

<figure><img src="https://content.gitbook.com/content/cO0A6g1dOsu8BiHYqO67/blobs/ySbsQf9eb484MDSV0Da1/consumers-header%20api%20key.png" alt=""><figcaption></figcaption></figure>

Se você deseja usar o *Basic Auth*, siga os passos abaixo:

1. Acesse o *header* e defina o valor da chave para o parâmetro *Authorization*.
2. O valor em *Authorization* deve ser um conteúdo Base64 formado por *Basic + Base64*(usuário :senha). Por exemplo: Basic YXF1aWxlcy1iYXNpYy0xMjM6MTIzNDU2

<figure><img src="https://content.gitbook.com/content/cO0A6g1dOsu8BiHYqO67/blobs/wE5ZERyRFvZK1kmcUSak/consumers-header%20basic%20auth.png" alt=""><figcaption></figcaption></figure>