API | Bling - Migração para autenticação JWT
Migração para autenticação JWT Introdução Este guia aborda detalhadamente a ativação e o uso de JSON Web Tokens (JWT) na API do Bling além de apresentar as instruções necessárias para a implementação dessa evolução em nossa arquitetura tecnológica e destacar os principais benefícios proporcionados por essa mudança.
Os principais tópicos da alteração que serão explicados detalhadamente nas seções subsequentes:
  • A data de bloqueio do uso de tokens opacos está em definição.
  • A autenticação utilizando tokens opacos está descontinuada.
  • Alteração no tamanho do token gerado.
  • Para obter JWT: Inclua o header enable-jwt: 1 ao obter um token por meio do endpoint POST /oauth/token. É fundamental manter este header em todas as requisições subsequentes para garantir que os tokens JWT continuem sendo emitidos após renovações.
  • Para renovar JWT: Inclua o header enable-jwt: 1 também na requisição de renovação do token para continuar recebendo tokens JWT.
  • Para usar JWT: Envie o header Authorization: Bearer {token} em todas as requisições à API que exigem autenticação.
Motivação da alteração Antes dessa evolução, a API do Bling somente utilizava tokens opacos para autenticação. Esse tipo de token é apenas uma referência, um identificador aleatório. Quando a API recebe um token opaco, o sistema precisa consultar um banco de dados ou mecanismo de cache centralizado para validar quem é o usuário e quais são suas permissões. Com o JWT essa abordagem mudou. Trata-se de um token estruturado e auto contido, ou seja, as informações sobre o usuário, a empresa e os escopos de permissão ficam codificadas no próprio token. Ganhos computacionais e de infraestrutura A adoção do JWT traz benefícios imediatos para a latência das requisições e uso de recursos computacionais:
  • Redução de I/O (Stateless): Ao usar JWT, a API não precisa necessariamente consultar o banco de dados para validar o token a cada requisição. A validação é feita criptograficamente (CPU), sendo computacionalmente mais eficiente do que operações de entrada/saída (I/O) em disco ou rede para buscar sessões em banco de dados.
  • Escalabilidade: Como o token carrega os dados necessários, a arquitetura torna-se stateless (sem estado). Isso facilita a escala horizontal dos serviços, pois qualquer servidor pode validar o token sem depender de uma central de sessões.
  • Eficiência de Rede: Embora o JWT seja maior do que um token opaco, a eliminação da necessidade de consultas adicionais ao banco de dados (round-trips) compensa o aumento do payload, especialmente em cenários de alta concorrência.
Estrutura e tamanho do token Diferente dos tokens opacos curtos, o JWT carrega um payload de dados em Base64. Com base na estrutura atual de informações contidas (claims), o tamanho de um token JWT pode variar aproximadamente de 1.500 a 3.000 caracteres. Atenção: É essencial que sua aplicação esteja preparada para armazenar e trafegar strings desse tamanho nos headers de autorização. Utilizando JWT no Bling Por padrão, a API do Bling retorna tokens opacos, contudo, esse modelo de autenticação está descontinuado. Para receber um token JWT ao invés de um token opaco, você deve incluir o header enable-jwt com o valor 1 na requisição ao endpoint POST /oauth/token. Importante: Sem o header enable-jwt, você receberá um token opaco que continuará funcionando até a migração total para o JWT. Migre o quanto antes, não deixe para o último momento. Exemplo de obtenção de token JWT Exemplo de renovação de token JWT Usando o token JWT nas requisições Após obter o token JWT através do endpoint POST /oauth/token, você deve incluí-lo em todas as requisições subsequentes à API. É fundamental que o header enable-jwt: 1 seja mantido em todas as requisições para garantir a compatibilidade e o processamento correto da autenticação JWT pela API. Este header deve ser incluído em todas as requisições que exigem autenticação, como consultar produtos, criar pedidos, etc. Exemplo de requisição para a API de produtos: Tratamento de erros comuns Ao implementar o uso do JWT, atente-se aos seguintes códigos de retorno:
401 Unauthorized: Indica que o token expirou ou é inválido. Solução: Renove o token usando o refresh_token (lembrando do header enable-jwt: 1) ou refaça o fluxo de autorização OAuth.
400 Bad Request: Geralmente indica token malformado ou erro na sintaxe do header. Solução: Verifique se o header segue estritamente o formato: Authorization: Bearer {token}.
Dúvidas? Entre em contato com nossa equipe de atendimento.