Como autenticar nas APIs do Zeev

Os tokens são códigos criptográficos vinculados a um usuário que permitem consumir as APIs do sistema

Visão geral

Para utilizar as API's do Zeev, será preciso um token de autenticação. O Zeev utiliza o método de autenticação conhecido como Bearer Token.

A autenticação de API usando Bearer Token é um método de segurança que garante que apenas usuários e sistemas autorizados possam acessar uma API.

Um "token" é como um cartão de acesso digital que o usuário recebe após uma verificação inicial. Sempre que ele fizer uma requisição à API, esse token é enviado como uma "prova" de que ele está autorizado a usar os serviços da API. É importante porque ajuda a proteger os dados sensíveis e impede que usuários não autorizados acessem ou modifiquem informações.

Permissões vinculadas ao token

Um token representa uma pessoa do sistema.

Por isso, as permissões de acesso em operações de API seguirão as mesmas regras de permissão de acesso a essa pessoa na interface do sistema e poderão ser impactadas, por exemplo, por seus grupos de manutenção. Pessoas sem privilégios administradores não conseguirão realizar determinadas operações ou poderão não ter acesso a todos os dados em consultas.

Por exemplo:

• Se a pessoa não possui permissão de criar um novo usuário, seu token não permitirá realizar essa operação por API;

• Se a pessoa não possui permissão de abrir uma determinada solicitação, seu token não permitirá essa operação por API;

• Se a pessoa não é responsável atual por uma determinada tarefa, seu token não permitirá essa operação por API;

Tipos de tokens

Existem dois tipos de tokens:

• Token (temporário): pode ser usado até 10 minutos após sua emissão;

• Token permanente: não tem data fixa de expiração;

Como obter o token de autenticação

O token é a representação de uma pessoa ativa e não bloqueada do sistema.

O token pode ser encontrado dentro do módulo de pessoas, dentro do cadastro de uma determinada pessoa, ao final da tela. Somente pessoas superadministradoras podem ver esse box.

Evite gerar e armazenar tokens de usuários superadministradores. É provável que nesse caso você esteja gerando um token com muitas mais permissões do que é necessário.

É altamente recomendável que seja criado um usuário específico no sistema somente para realizar integrações.

Esse usuário deve ter uma senha extremamente segura e possuir permissões somente nas operações que efetivamente sejam necessárias junto às APIs.

Utilizar tokens de usuários comuns pode acarretar os seguintes problemas:

• A pessoa pode ser desativada do sistema por outros motivos e todas as integrações pararem de funcionar;

• A pessoa ter permissões demais, desnecessárias para as integrações, e isso acarretar um problema de segurança;

Para saber como obter um token de autenticação via API consulte Tokens / Segurança

Como enviar o token para chamadas de API

Em todas as chamadas de API do Zeev, você precisará enviar o token de autenticação. O token é enviado através do cabeçalho / header da solicitação, com a chave Authorization e prefixo Bearer:

Authorization: Bearer token-de-autenticação

Veja, abaixo, exemplos de como enviar o token em Javascript, C# e Python. A expressão TOKEN-DE-AUTENTICACAO deve ser trocada pelo respectivo token.

Node.js

//javascript
async function fetchData() {
  const url = 'https://api.exemplo.com/dados';
  const headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer TOKEN-DE-AUTENTICACAO'
  };

  try {
    const response = await fetch(url, { headers: headers });
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error:', error);
  }
}

fetchData();

C#

static async Task Main()
{
    using (HttpClient client = new HttpClient())
    {
        client.DefaultRequestHeaders.Add("Authorization", "Bearer TOKEN-DE-AUTENTICACAO");

        try
        {
            HttpResponseMessage response = await client.GetAsync("https://api.exemplo.com/dados");
            response.EnsureSuccessStatusCode();
            string responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseBody);
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine("\nException Caught!");
            Console.WriteLine("Message :{0} ", e.Message);
        }
    }
}// Some code

Python

import requests

url = "https://api.exemplo.com/dados"
headers = {
    "Authorization": "Bearer TOKEN-DE-AUTENTICACAO"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)

Atenção: jamais faça integrações com API's do Zeev com Javascript executando dentro de um navegador de internet. Utilize Javascript somente executando em um servidor (exemplo: Node.js). Qualquer pessoa pode obter o código-fonte de sua página e obter o token de autenticação. De posse do token, poderá acessar o sistema.

Como configurar minha aplicação terceira para usar os tokens

Se você tem um sistema externo e deseja se conectar nas APIs do Zeev, siga os passos abaixo:

1. Obtenha o token permanente de um usuário ;

2. Salve ele no código em um arquivo de configuração do seu sistema, de maneira segura.

Salve e guarde o token como uma senha especial. Salve ele em arquivos de configuração seguros, que não possam ser acessados por usuários finais. Salve ele em locais em que você você, futuramente, se necessário, facilmente trocá-lo.

Melhores práticas e passo a passo de como configurar

Nos vídeos abaixo explicitamos melhor prática de como configurar permissões, usuários e tokens.