Como gerar e gerenciar App Token e Access Token para integração via API

Visão geral

A integração de aplicações externas com a plataforma exige chaves de autenticação para validar requisições e gerenciar permissões de acesso às informações. O App Token identifica o cadastro da licença junto à API, enquanto o Access Token define o escopo de permissões do usuário vinculado à integração. Ambas as chaves possuem validade de 1 ano, exigindo renovação periódica para a continuidade do serviço.

Quando usar este artigo

Utilize este artigo para orientar o procedimento de criação, consulta e renovação de tokens de acesso (App Token e Access Token) necessários para integrar sistemas proprietários ou de terceiros à API.

Sintoma ou cenário

Necessidade de realizar a configuração inicial de uma integração via API com a plataforma ou de revalidar as credenciais de acesso devido à expiração do prazo de validade de 1 ano das chaves de autenticação.

Benefício para o usuário ou operação

Validação segura na autenticação de requisições de sistemas externos via API;
Controle individualizado de acesso baseado nas permissões atribuídas ao usuário do token;
Conformidade com padrões de segurança operacional por meio da renovação anual de credenciais.

Onde acessar / contexto de uso

Menu do usuário (canto superior direito) > Todos os usuários > Aplicativos.

Pré-requisitos (Antes de começar)

Perfil Exato: Usuário com perfil de acesso contendo as permissões Usuários - Alteração e consulta (1010) ou Acesso Administrativo (1000).
Recursos Sistêmicos: Funcionalidade de gestão de usuários e acesso à API habilitados na licença.
Insumos e Dados Técnicos: Nome do aplicativo e descrição do objetivo da integração.

Causas prováveis

Implantação de novos aplicativos ou ferramentas que consomem os serviços da API;
Expiração do ciclo de validade de 1 ano do App Token e Access Token atualmente em uso.

Como fazer ou corrigir

O App Token e o Access Token possuem validade de exatamente 1 ano a contar da data de geração. Para manter o funcionamento contínuo das integrações, novos tokens devem ser gerados antes do vencimento. Apenas as chaves App Token e Access Token são exigidas para a autenticação nas requisições da API.

Passe o cursor do mouse sobre a foto ou nome do usuário no canto superior direito e clique em Todos os usuários (ou acesse a URL [http://superlogica.net/usuario](http://superlogica.net/usuario)).
Na lista de usuários, localize o cadastro desejado, desça a página e clique na opção Aplicativos ([e-mail do usuário]).
Clique no botão Novo App Token.
Preencha os campos Nome e Descrição do aplicativo (ambos obrigatórios) e clique em Salvar.
Na tela seguinte, visualize e copie os códigos gerados para App Token e Access Token.
Para consultar os endpoints e instruções técnicas de consumo, clique no botão Saiba como integrar para abrir a documentação de API.

Resultado esperado

Geração e exibição das chaves App Token e Access Token na tela, possibilitando a configuração da autenticação no sistema integrado.

Quando escalar

Escalar para a equipe de suporte quando a tela de geração de tokens apresentar mensagens de erro ao salvar as informações ou quando as chaves geradas retornarem falhas de autenticação na API mesmo estando dentro do prazo de validade.

Informações que devem ser reunidas antes do escalonamento

Nome da licença,
E-mail do usuário no qual o token foi cadastrado;
Nome do aplicativo configurado;
Endpoint da API acionado e o código/mensagem de erro retornado pela requisição.

Regras importantes / Observações

O prazo de validade das chaves App Token e Access Token é de 1 ano. Após esse período, é necessário gerar um novo token para restabelecer a integração;
Apenas os campos App Token e Access Token são necessários para realizar a autenticação das requisições na API;
A seção Aplicativos liberados, localizada acima da interface de criação, lista todos os aplicativos disponíveis para integração na licença.

Problemas comuns e como resolver

Falha de autenticação na API (Token expirado)
- Causa provável: O App Token ou Access Token atingiu o limite de 1 ano de validade.
- Ação recomendada: Acesse o cadastro do usuário na aba Aplicativos, gere um novo App Token e atualize as credenciais no sistema que consome a API.
Permissão negada ao executar chamadas na API
- Causa provável: O usuário associado ao Access Token não possui a permissão necessária para acessar o recurso no sistema.
- Ação recomendada: Verifique o perfil do usuário em Todos os usuários e conceda as permissões requeridas para a operação desejada.

Dúvidas relacionadas

P: Qual é o prazo de validade do App Token e do Access Token? R: Ambas as chaves possuem validade de 1 ano. Após esse período, para continuar utilizando a API, é necessário gerar um novo token.

P: Quais dados gerados na tela são obrigatórios para realizar a integração via API? R: Apenas os campos App Token e Access Token são necessários para autenticar a integração.

P: Onde é possível consultar a documentação técnica da API? R: Na tela de exibição dos códigos do token gerado, clique no botão "Saiba como integrar" para redirecionar para a documentação da API.

Palavras-chave de busca

app token, access token, integração api, chave de autenticação, gerar token, renovar token, token expirado, aplicativos liberados, credenciais api