Gerar o token de acesso da API
Caminhos: Configurações → Permissões (grupo de API) e Usuários → [usuário] → Cadastro → Permissões
Visão geral
O token de acesso identifica o usuário que chama a API do Opa! Suite e vale como uma senha. Ele é gerado para um usuário que tem o acesso à API liberado e um grupo de permissão de API vinculado. Assim, a integração só acessa os dados que o grupo permite. Veja como a API funciona em API do Opa! Suite.
Pré-requisitos
- Permissão Grupos de permissão, para criar o grupo de API.
- Permissão Alterar permissões dos usuários, para liberar o acesso à API e gerar o token. Sem ela, o sistema mostra o aviso Edição de permissões bloqueada.
- Um usuário para a integração. Recomenda-se um usuário só para a API. Veja Usuários.
Passo a passo
Criar o grupo de permissão de API
- Acesse Configurações → Permissões.
- Clique em Adicionar novo.
- Preencha os campos:
- Nome: nome que identifica o grupo.
- Nível de acesso: escolha uma das opções (Administrador, Gestor ou Operador). Num grupo de API, o que vale são as permissões de API marcadas na próxima etapa.
- Grupo exclusivo para API: ative. Depois de salvo, essa opção não pode ser alterada.
- Clique em Salvar.
- Clique no grupo criado e abra a aba Permissões.
- Marque as permissões que a integração pode usar e clique em Salvar alterações. Num grupo de API novo, todas começam desmarcadas. Veja o que cada uma libera em Funções de cada permissão.
Liberar o acesso à API para o usuário
- Acesse Usuários e clique no usuário da integração.
- Na aba Cadastro, na seção Permissões, clique em Editar informações.
- Ative Possui acesso à API do sistema.
- Em Grupo de permissões da API, selecione o grupo criado. O campo é obrigatório quando o acesso à API está ativo. Só aparecem grupos exclusivos para API.
- Clique em Salvar.
Copiar o token
- Ao salvar pela primeira vez, abre a janela Token API gerado com sucesso, com o Token de autenticação.
- Clique no token para copiá-lo.
- Clique em Concluir.
A janela avisa: "Copie o token agora. Após fechar esta janela, ele não estará mais visível." Depois, a seção Permissões mostra apenas o início e o fim do token. Se você não copiou, gere um novo token.
Gerar um novo token
- No cadastro do usuário, na seção Permissões, clique em Gerar novo token.
- Leia o aviso: o token atual é desativado na hora e todas as integrações que o usam deixam de funcionar.
- Clique em Gerar novo token.
- Copie o novo token e clique em Concluir.
- Atualize o token em todas as integrações que usavam o anterior.
Resultado esperado
O usuário passa a ter um token de autenticação. A integração envia esse token no cabeçalho Authorization de cada requisição e acessa só o que o grupo de API permite.
Se você desativar Possui acesso à API do sistema e salvar, o token e o vínculo com o grupo de API são removidos.
Problemas comuns
| Sintoma | O que verificar |
|---|---|
| O botão Gerar novo token não aparece | O acesso à API do usuário ainda não foi liberado. Ative Possui acesso à API do sistema e salve. |
| O botão Gerar novo token está bloqueado | Seu grupo não tem a permissão Alterar permissões dos usuários. |
| O campo Grupo de permissões da API não lista o grupo | O grupo precisa ter sido criado com Grupo exclusivo para API ativo. |
| A integração parou de funcionar | Um novo token foi gerado. Atualize o token na integração. |
A API responde erro 403 | O grupo de API não tem a permissão do recurso, ou a rede de origem não está nas Redes permitidas. Veja [[api opa! suite |
Boas práticas
- Guarde o token em um cofre de senhas, não em planilhas nem em mensagens.
- Use um usuário e um grupo de API por integração, para poder trocar o token de uma sem afetar as outras.