Tokens e aplicativos
Sistemas externos acessam a API da Kobana com um token de API ou por um aplicativo OAuth. Esta página mostra onde criar e controlar essas credenciais no painel. O funcionamento técnico (cabeçalhos, escopos, fluxo OAuth) está em Autenticação.
Tokens de API da conta
Onde fica
Menu Integrações > API > Tokens de API. A lista tem as abas Ativos e Revogados. Tokens gerados por aplicativo OAuth aparecem com um ícone de escudo.
Criar um token
Clique em Criar novo Token de API, preencha os campos e salve.
| Campo | Obrigatório | Descrição |
|---|---|---|
| Descrição | Não | Identifica o uso do token, até 100 caracteres. Exemplo: "Token para integração com ERP". |
| Escopos | Sim | Acesso completo (todos os escopos) ou Escopos específicos, escolhidos em lista ou digitados um por linha em Definir por digitação. |
| Nível de Acesso | Sim | Somente leitura ou Leitura e escrita. |
| Validade | Sim | Data de expiração, no máximo 1 ano a partir de hoje. |
| E-mails para notificação de expiração | Sim | Pelo menos um e-mail que recebe o aviso de expiração. |
| Etiquetas (Tags) | Não | Separe com vírgulas. |
Regras:
- Tokens com Acesso completo só podem ser de Somente leitura. Para conceder escrita, escolha escopos específicos.
- Leitura e escrita permite que o token execute comandos no banco, como registrar um Pix, efetuar um pagamento ou fazer transferências, se os escopos correspondentes estiverem marcados.
- A validade não pode ser alterada depois. Para mudar, revogue o token e crie outro.
- Os escopos disponíveis respeitam a Permissão de Escopos da conta.
- O token herda o usuário que o criou: ele só faz o que esse usuário tem permissão para fazer.
O token é exibido uma única vez, logo após a criação. Copie e guarde em local seguro e clique em Já salvei!. Se perder o token, será preciso renovar ou criar outro.
Ações do token
| Ação | O que faz | Restrição |
|---|---|---|
| Alterar | Edita descrição, escopos, nível de acesso, e-mails e etiquetas. | Token não revogado e não expirado. |
| Desabilitar / Habilitar | Suspende ou reativa o token, sem perdê-lo. | Token não revogado e não expirado. |
| Renovar Token | Cria um token novo com a mesma configuração e revoga o atual. | Token habilitado e não expirado. |
| Revogar Token | Invalida o token de forma definitiva. | O token precisa estar desabilitado. |
| Excluir | Remove o token da lista. | Só token revogado ou expirado. |
Todas as ações ficam registradas na Auditoria.
Permissões: Segurança > Tokens da API (Ações Básicas, Criar, Alterar, Excluir, Habilitar, Desabilitar, Renovar, Revogar).
Tokens pessoais
Cada usuário pode criar tokens em nome próprio na Conta Kobana: menu do usuário > Gerenciar Conta > Tokens e Acesso > Meus Tokens Pessoais.
A criação é feita em três passos:
- Aplicativo: escolha o aplicativo Kobana que o token vai acessar e como ele será usado. O token só vale no aplicativo escolhido.
- Recursos: Todos os recursos (apenas leitura) ou Recursos específicos, com o acesso de escrita marcado por recurso.
- Validade: 7 dias, 30 dias, 3 meses, 6 meses, 1 ano ou uma data personalizada, além dos e-mails de aviso de expiração e das etiquetas.
Os tokens pessoais também aparecem na lista de Tokens de API da conta. Permissões: Perfil > Meus Tokens da API.
Aplicações Autorizadas
Em Tokens e Acesso > Aplicações Autorizadas, cada usuário vê as aplicações OAuth de terceiros que autorizou a acessar a conta em nome dele. Revogar uma autorização invalida todos os tokens emitidos para aquela aplicação; a integração precisa ser autorizada de novo.
Permissão de Escopos
Em Tokens e Acesso > Permissão de Escopos, a conta define quais escopos podem ser usados nos tokens criados por ela e pelas subcontas.
- Sem nenhum escopo marcado, a conta permite todos os escopos.
- Marcando escopos, só eles podem ser atribuídos a novos tokens. Os escopos são agrupados por aplicativo, em abas.
- Antes de salvar uma restrição, a tela mostra quantos tokens em uso perdem acesso a algum escopo. Esses tokens perdem o acesso na hora, sem precisar de revogação, e as chamadas que dependem dos escopos bloqueados passam a ser recusadas.
- Uma subconta sem restrição própria herda os escopos permitidos da conta principal. Com restrição própria, valem só os escopos marcados nela que também são permitidos pela conta principal.
- Só o Proprietário da conta pode alterar esta configuração, e ele precisa da permissão Segurança > Segurança da API > Escopos Autorizados. Os demais usuários veem a tela em modo leitura.
Aplicativos OAuth
Contas que desenvolvem integrações para outros clientes da Kobana cadastram aplicativos OAuth em Tokens e Acesso > Apps OAuth. O item aparece para contas do tipo empresa ou ERP.
Campos principais: Nome da aplicação (exibido na tela de autorização), Descrição, Nome interno (opcional), Nome do desenvolvedor, Website do desenvolvedor, URLs de redirecionamento, escopos e se a aplicação é confidencial.
- O secret da aplicação é exibido uma vez, logo após a criação, e pode ser renovado a qualquer momento.
- Um aplicativo em rascunho pode ser enviado para avaliação da Kobana. Quando a edição está bloqueada, a tela informa "Esta aplicação está bloqueada para edição. Entre em contato com o suporte para liberar alterações." A renovação do secret continua disponível mesmo assim.
Permissões: Integrações > Aplicativos OAuth (Ações Básicas, Criar, Alterar, Excluir).
Pela API
Tokens também podem ser criados, alterados e revogados pela API V2. Veja a referência da API V2 e a página de Autenticação.