APIs de Vindi Recorrência passarão a exigir o padrão RFC2617 de autenticação

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.