Credenciais

Uma credencial tem como objetivo possibilitar o acesso a uma API, que por sua vez pode ter acesso a todas as aplicações disponíveis ou apenas a uma específica. Através da credencial, são configuradas as APIs e definidos os escopos, sendo essencialmente um processo de autenticação das credenciais do Auth para confirmar sua legitimidade. Para iniciar o cadastro, pressione o botão +CREDENCIAL, logo, será apresentado os tipos de credenciais.

Aplicação no Browser

Usada em aplicações onde login e senha são transmitidos. O fluxo ocorre da seguinte forma: a ferramenta Auth envia um usuário e senha e, em seguida, recebe um código que é enviado novamente para o Auth, que então retorna o token.

É uma aplicação de front-end em nome de um usuário, ou seja, quando o parceiro desenvolve um produto que segue um fluxo de front-end.

Para essa credencial são utilizados os fluxos de Authorization Code com PKCE (Recomendado) ou Implicit (Não recomendado)

Aplicação no Servidor

São APIs consumidas por aplicações back-end em nome de um usuários, com o token armazenado no servidor. Por exemplo, ao fazer login em um sistema, o acesso à API é realizado usando as credenciais do servidor. Essa credencial é associada a uma chave pública e uma chave privada, gerando um access-token.

Para essa credencial é utilizado o fluxo de Authorization Code

Serviço

As API's são consumidas em nome da própria aplicação e o token não expira. Além disso, ao renovar o token, o anterior permanece válido. Ou seja, mesmo que um novo token seja gerado, o anterior continua funcionando normalmente. É importante lembrar que atualmente não há maneira de revogar um token gerado anteriormente e o campo Webhook é utilizado ao liberar uma aplicação em um sistema e envia um evento para o endpoint cadastrado, contendo o acesso do usuário que foi concedido. Esse tipo de integração é para consumo de API's direto, como: gerar Estado e BI.

Para essa credencial é utilizado o fluxo de Client Credentials

Anônima

No caso de uma conexão anônima, o serviço se autentica com a Betha, porém não há um usuário individual vinculado a ele. Isso significa que certas áreas do sistema Betha possuem integrações com funcionalidades que não exigem autenticação. Por exemplo, é possível obter uma guia de IPTU com base no CPF.

Para essa credencial são utilizados os fluxos de Authorization Code com PKCE (Recomendado) ou Implicit (Não recomendado)

Usuário e senha

são utilizados pelos aplicativos móveis, seguindo um fluxo semelhante ao da aplicação no navegador, porém mais simplificado: o aplicativo envia as credenciais de usuário e senha e, em troca, recebe o token de acesso.

Para essa credencial é utilizado o fluxo de Fluxo de Resource Owner Password, porém seu uso é restrito para uso interno da Betha Sistemas

IMPORTANTE!

Será demonstrado como criar uma credencial de serviço, uma das mais utilizadas por incorporar todas as funcionalidades disponíveis em uma credencial.

Ao selecionar a credencial de serviço e inserir o nome da aplicação que será construída, uma nova janela será apresentada com as chaves pública e privada já preenchidas automaticamente. Continue lendo para aprender como gerar o Token de acesso e o User Access.

Gerando Token de Acesso

Token de acesso é uma credencial de autorização que atua como uma "chave" única para várias entidades. Ele é usado para autenticar e autorizar requisições nos endpoints de uma API.

Para obter informações sobre os endpoints, é disponibilizado um guia na seção Documentação nos detalhes da API. Para habilitar uma API em uma credencial, é necessário acessar nosso catálogo de API´s, disponível através do botão “Pesquisar na Betha Store”.

Por exemplo, conforme exibido abaixo, vamos habilitar uma API em uma credencial: inicialmente, acesse o catálogo de API´s e selecione a API desejada, então defina os escopos (escrita, leitura, etc…) e ative a API para a credencial desejada.

Suponha que inicialmente dois escopos tenham sido selecionadas, mas em um momento posterior, precise desmarcar um deles ou adicionar novos. Nesse caso, é necessário renovar o token e um novo token será gerado. O novo token terá acesso às novas configurações da API. No entanto, não se preocupe, pois essa ação não invalida o token anterior, que continuará funcionando conforme as configurações anteriores.

Materiais para consulta: Consulta dados das entidades do escopo e Fonte de dados para consulta de dados de entidades.

Gerando User-Access

User-access é específico para cada entidade consumida, permitindo identificar o banco de dados e a entidade para acessar os dados.

Para solicitar o User Access, é necessário clicar no botão Solicitar na tela que exibe as chaves da credencial. Ao clicar nesse botão, uma nova tela será apresentada, onde o parceiro deverá clicar no botão +Solicitação. Nessa nova tela, é preciso informar o sistema e a entidade que deseja acessar os dados. Após clicar em salvar, um representante comercial será notificado para realizar a liberação. O parceiro poderá verificar o status da solicitação, que pode estar marcado como Liberado, Em análise ou Rejeitado.

IMPORTANTE!

Essa liberação é realizada pela Betha, mas não neste momento que será gerado o user-access, ainda necessita de um segundo passo.

Após a liberação feita pela Betha, é preciso copiar a chave pública e enviá-la à entidade responsável para que esta realize a liberação no sistema onde os dados serão consumidos. O responsável pela entidade deverá acessar Gerenciador de acessos > Aplicações, clicar em +Aplicação e inserir a chave pública fornecida pelo parceiro, logo, é mostrada a integração que será realizada, na aba confirmação é mostrado uma mensagem em que o parceiro terá acesso a determinados recursos selecionados no Studio Aplicações. Ao confirmar é gerado a chave de acesso que nada mais é que o User Access, logo, o parceiro pode pegar a chave através do link Ver detalhes localizado na tela de informações da credencial no Studio.

Cadastrando uma redirect_uri

O cadastro de redirect_uri é feito através do Studio Aplicações

IMPORTANTE!

Para fluxos que envolvem redirect (Authorization code, Authorization Code Implicit e Authorization Code com PKCE) é necessário cadastro de uma redirect_uri válida.