TOKEN DE ACESSO

Overview

Após a geração do token local formado acima, é preciso fazer uma chamada para o nosso servidor de Autenticação para que a gente faça a validação e retorne o Token de Acesso.

Provido com o Token de Acesso (token que já foi autenticado), você poderá acessar os endpoints da aplicação, que antes estavam restritos. Para realizar esse acesso, é preciso informar esse token no header Authorization da requisição e, por convenção, após a palavra Bearer.

Em seguida, vamos te guiar para realizar as seguintes etapas para obtenção do seu Token de Acesso:

Gerar um par de chaves de acesso

Cadastrar sua Aplicação

Fazer a Autenticação

Realizar Chamada Autenticada

Gerar Chaves de acesso

Embora existam vários métodos para criação de pares de chaves pública e privada, a ferramenta OpenSSL de código aberto é uma das mais usadas, por isso, recomendamos o seu uso.

Em todas as plataformas disponíveis - Linux, MacOS e Windows, os comandos do OpenSSL são iguais:

   $ openssl genrsa -out mykey.pem 4096
   $ openssl rsa -in mykey.pem -pubout > mykey.pub

Algumas dicas importantes:

Agora você já pode gerar o seu par de chaves. A chave pública será solicitada pelo nosso time durante a integração. Nós deixamos a chave pública guardada de forma segura e a usaremos para validar o seu token num processo de criptografia assimétrica.
A chave que deverá ser enviada para a Stone através do formulário de integração é sempre a chave pública (arquivo .pub).

Atenção!

Você nunca deve compartilhar a chave privada (arquivo.pem)! A chave privada deve ser armazenada de forma segura por você.
Em posse da sua chave privada, qualquer aplicação pode decodificar a assinatura e verificar se ela é válida.
Por isso destacamos a importância de manter essa informação em segredo.

Depois de obter seu par de chaves, você está pronto para iniciar conosco o Cadastro da Aplicação.

Cadastro da Aplicação

Qualquer parceiro ou cliente que deseje acessar e/ou movimentar a sua conta ou de terceiros pela nossa API precisará ter sua aplicação identificada. O identificador que representa a sua aplicação na Stone é chamado ClientID.

O ClientID será usado no processo de Autenticação, permitindo a identificação da origem dos requests feitos por API. Ou seja, ele será usado no seu Token de Acesso para realizar chamadas. O ClientID é gerado pela Stone, é único e não será alterado posteriormente.

Para obter um ClientID, você deverá entrar em contato com nosso time comercial. Em seguida, pediremos algumas informações para cadastrar sua aplicação. Nesse formulário, será necessário enviar ao time da Stone:

1. A sua chave pública - que será atrelada ao cadastro da sua aplicação.
2. Uma URI de Redirect - precisamos de um local público para redirecionarmos o usuário final depois que ele aprovar ou reprovar o Consentimento de acesso à sua plataforma. Caso você esteja fazendo a integração para acesso à sua própria conta, pode desconsiderar essa etapa.
3. Uma URI de webhooks - precisamos de um local público para enviar mudanças de estado das contas para aplicações. Essa URI irá receber as informações dos webhooks para seu processamento.
4. Sua linguagem de desenvolvimento - nossa infraestrutura disponibiliza uma API RESTful com respostas em JSON.

Após o recebimento de todas as informações e cadastro da sua aplicação, enviaremos o seu ClientID por e-mail.

Atenção! O ClientID será enviado para o e-mail identificado no formulário como dono da aplicação. Caso você queira movimentar a sua própria conta, esse e-mail deverá ser o mesmo cadastrado no momento de abertura da Conta.

Pronto! Com seu ClientID em mãos, você já pode realizar o processo de Autenticação.

Autenticação

Para realizar o processo de Autenticação, você deverá enviar uma requisição ao nosso servidor contendo um JWT. O JWT enviado deverá conter as credenciais da sua aplicação (ClientID e deverá ser assinado com a chave privada. Ao receber o request, faremos o processo de validação do token enviado, pois já teremos recebido e armazenado a sua chave pública.

Uma vez que o token seja válido e tenha sido autenticado em nosso servidor, enviaremos como resposta o Access Token, ou seja, o seu Token de Acesso.

Padrões utilizados na Autenticação

Para facilitar ao máximo a integração com nossa API, escolhemos padrões estabelecidos no mercado para realização do processo de autenticação - descritos abaixo.

OAuth 2.0 é um padrão de autorização que vai permitir ao usuário conceder acesso limitado a recursos na Conta Stone para aplicações sem a necessidade de expor suas credenciais. Isso significa que o cliente não precisará compartilhar login e senha com ninguém.

OpenID Connect é uma camada de identidade construída em cima do OAuth 2.0 que permite a fácil verificação da identidade do usuário, bem como a capacidade de obter informações básicas de perfil do provedor de identidade - no nosso caso, a Conta Stone.

Especificações do JWT para realizar autenticação

Primeiramente, temos que gerar um token JWT local para conseguir fazer a autenticação com sucesso. Esse token deverá ser preenchido com as claims com os seguintes valores:

Após gerar esse token localmente, partiremos para receber o access_token e realizar as chamadas autenticadas.

O request para receber o access_token é realizado através do método POST com as informações abaixo:

Header
Na nossa API, usaremos sempre o algoritmo RS256. Esse algoritmo especificado nessa RFC usa criptografia “RSASSA-PKCS1-v1_5 com SHA-256”. Abaixo você encontrará um exemplo de header.

{
  "alg": "RS256",
  "typ": "JWT"
}

A chamada é com o método POST, com os headers Content-Type e User-Agent.
O Content-Type informado deve ser x-www-form-urlencoded (o mesmo usado por submissão de formulários HTML) e o header User-Agent deve estar habilitado com o nome da sua aplicação. Verifique o exemplo abaixo:

{
  "user-agent": "Nome da aplicação",
  "content-type": "application/x-www-form-urlencoded"
}

Payload
É um objeto JSON que trará as informações que usaremos para verificar a autenticidade da chamada e retornar o Token de Acesso. É necessário enviar o campo client_id, o campo grant_type, que será um campo de valor fixo (client_credentials), o campo client_assertion, que será o token gerado localmente citado acima, e por último o campo client_assertion_type, que também terá seu valor fixo (urn:ietf:params:oauth:client-assertion-type:jwt-bearer), fechando o fluxo de client credentials para o servidor.

Você deverá receber como resposta um JSON com uma chave, ou seja, o seu Token de Acesso, que permitirá que você faça Chamadas Autenticadas.

Chamada autenticada

Após realizar o processo de Autenticação e receber como resposta o seu Token de Acesso, basta colocá-lo no header Authorization. Você irá usar o valor recebido para preenchimento do Bearer ACCESS_TOKEN de todas as chamadas realizadas em nossa API.

Além do Token de acesso, é necessário preencher sempre no header o campo User-Agent, que deve estar habilitado com o nome da sua aplicação.

Para realizar chamadas autenticadas em nossa API, disponibilizamos as seguintes URLs:

A seguir, vamos te guiar pela seção Conta de Pagamento, onde você poderá entender mais sobre as características do nosso negócio e sobre o processo de abertura de conta.

Collection do Postman

Para ajudar na realização das chamadas autenticadas, disponibilizamos alguns endpoints e códigos prontos!

Você pode baixar clicando nos links abaixo:

• Código em JS para geração do link de consentimento
• Código em Python para geração do token de autenticação
• Código em Python para pedido de criação para contas Stone
• Collection do Postman para criar Pagamentos
• Collection do Postman para realização de Pix
• Collection do Postman para Transferências
• Collection do Postman para Dados da Conta (inclui extrato)
• Collection do Postman para Simulações(Dry-run)
• Collection do Postman para emissão de Comprovantes
• Collection do Postman para Link de Pagamento
• Collection do Postman para Recargas
• Collection do Postman para Boletos