O que está acontecendo
Algumas bibliotecas e/ou frameworks utilizados nos sistemas dos nossos clientes que integram com as APIs da Vindi Recorrência não utilizam o padrão RFC2617 de autenticação em suas requisições.
O padrão RFC2617 determina que as requisições sejam enviadas com usuário e senha, separados por dois pontos (:) e codificadas em Base64, mesmo para senhas em branco.
Authorization: Basic {credenciais em Base64 no formato username:password}
Por que a Vindi fará essa mudança
Para adequar as APIs de Vindi Recorrência ao padrão RFC2617 de autenticação.
Ação requerida
Clientes que utilizam as APIs da Vindi Recorrência precisam adequar suas integrações para atender o padrão determinado no RFC2617.
Caso não se adequem ao padrão, as requisições serão bloqueadas com um retorno de status code 401 Unauthorized.
Para bibliotecas ou frameworks que já implementam o padrão RFC2617, nenhuma ação será necessária.
Exemplo de requisição utilizando o comando curl:
curl https://app.vindi.com.br/api/v1/payment_methods \
-H Content-Type:application/json \
-u API_KEY:
No exemplo acima, a autenticação é informada com o atributo -u no formato username:password. Conforme foi mencionado, não é necessário informar a senha, porém o separador ":" continua obrigatório.
As autenticações em que o separador ":" não é informado, passarão a ter um retorno de 401 Unauthorized na resposta da requisição.
Como validar se a sua integração será afetada?
Validar a autenticação da sua integração envolve verificar se as credenciais fornecidas estão no formato padrão esperado, com base em uma combinação de codificação (base64). As credenciais são enviadas no cabeçalho HTTP da requisição.
Exemplo de requisição:
curl --request GET \
--url https://sandbox-app.vindi.com.br/api/v1/merchants/current \
--header 'Authorization: Basic WWx5UExSS3FOcmxuVzlMWjo=' \
--header 'Content-Type: application/json' \
--data '{}'
Neste exempĺo, WWx5UExSS3FOcmxuVzlMWjo= é a string codificada em base64 que representa as credenciais no formato YlyPLRKqNrlnW9LZ:, onde
- YlyPLRKqNrlnW9LZ é a representação de uma chave de API gerada na Vindi;
- : é o delimitador do nome do usuário (que na Vindi é a chave de API) e a senha (que na Vindi podemos deixar em branco).
Ao decodificador a string WWx5UExSS3FOcmxuVzlMWjo=, observamos que a credencial passada no header está dentro do padrão determinado. ✅
Exemplo de decodificação usando uma biblioteca em Ruby
irb(main):001:0> require "base64"
irb(main):002:0> credential = "WWx5UExSS3FOcmxuVzlMWjo="
irb(main):003:0> Base64.decode64(credential)
=> "YlyPLRKqNrlnW9LZ:"
Note que o resultado das credenciais decodificadas seguem o padrão de user:password e a integração não será afetada nesse exemplo.
O resultado da requisição para essa autenticação válida é um código HTTP 200.
HTTP/2 200
content-type: application/json; charset=UTF-8
Agora, vamos simular uma integração que não está dentro dos padrões esperados, utilizando o mesmo exemplo de chave de API: YlyPLRKqNrlnW9LZ .
Exemplo de requisição:
curl --request GET \
--url https://sandbox-app.vindi.com.br/api/v1/merchants/current \
--header 'Authorization: Basic WWx5UExSS3FOcmxuVzlMWg==' \
--header 'Content-Type: application/json' \
--data '{}'
Ao decodificador a string WWx5UExSS3FOcmxuVzlMWg==, observamos que a credencial passada no header não está dentro do padrão determinado e não tem o delimitador :, ela está codificada apenas com a chave de API. ❌
irb(main):001:0> require "base64"
irb(main):002:0> credential = "WWx5UExSS3FOcmxuVzlMWg=="
irb(main):003:0> Base64.decode64(credential)
=> "YlyPLRKqNrlnW9LZ"
O resultado da requisição para essa autenticação inválida é um código HTTP 401.
HTTP/2 401
www-authenticate: Basic realm="API Authorization"
No corpo da resposta da requisição, o conteúdo abaixo será retornado:
{
"errors": [
{
"id": "unauthorized",
"parameter": "authorization",
"message": "Chave da API inválida"
}
]
}
Os exemplos foram feitos no endereço de sandbox, mas podem servir como exemplo para validar no endereço de produção.
Cronograma de alteração
-
Sandbox: 12/11/2024 - concluído
-
Produção:
-
14/01/2025 - concluído: deploy e rollback
- 14h45 - deploy em produção
- 15h20 - rollback
-
ℹ️ Nova data de subida em produção: à definir.
Os prazos estão sujeitos à alterações. Para acompanhar o cronograma atualizado, consulte este artigo.
Dúvidas e suporte
Caso tenha dúvidas sobre a mudança, contate o nosso suporte.
Comentários
5 comentários
Thais
Posso usar esse novo padrão de autenticação hoje em Produção, ou tenho que esperar 06/01/2025 para alterar na minha aplicação ?
Clertis Liboni pode usar em produção sim, sendo o padrão, você não deverá ter problemas.
Você pode testar no nosso sandbox para validar que está tudo certo e depois já aplicar em produção.
A virada para produção só afetará que não estiver no padrão de autenticação.
Obrigado Thais Kusuki Yabiku
Bom dia! Esse chaveamento já ocorreu? Continuo no formato antigo e ainda está funcionando. Obrigado!
Caio Graco bom dia. Subirá por volta de 14h.
Por favor, entre para comentar.