Processo de Autenticação

Bem-vindo ao guia de autenticação para acesso às APIs da Orkestral.

Siga as instruções abaixo para configurar suas credenciais, obter um token de acesso e realizar requisições autenticadas às APIs da plataforma.

Objetivo

Orientar os clientes sobre como obter, renovar e utilizar um token de acesso para consumir os recursos protegidos das APIs da Orkestral.

A autenticação atual utiliza OAuth 2.0 com credenciais do cliente, email e senha do usuário.

Ambientes

Ambiente	URL base
Homologação	https://api-qas.orkestralpay.com.br
Produção	https://api.orkestralpay.com

Utilize somente a URL correspondente ao ambiente disponibilizado para sua integração.

Pré-requisitos

Para realizar a autenticação, é necessário:

• possuir uma conta ativa na Orkestral;
• ter um usuário vinculado ao merchant;
• possuir o email e a senha desse usuário;
• possuir o client_id e o client_secret fornecidos pela Orkestral durante o onboarding;
• utilizar uma conexão HTTPS.

Credenciais utilizadas

O processo utiliza dois conjuntos de credenciais.

Credenciais do cliente OAuth

As credenciais do cliente identificam a aplicação que está solicitando o token:

• client_id;
• client_secret.

Essas credenciais são enviadas no cabeçalho Authorization utilizando Basic Auth.

Credenciais do usuário

As credenciais do usuário identificam quem está realizando a autenticação:

• username: email cadastrado na Orkestral;
• password: senha correspondente ao usuário.

Diferença entre o client secret e a Chave Secreta

O client_secret da autenticação OAuth não é a mesma Chave Secreta apresentada na página Integração da plataforma.

• O client_secret é utilizado para autenticar o cliente OAuth e obter tokens.
• A Chave Secreta da página Integração é utilizada na validação do checksum das notificações.

aviso

Não utilize a Chave Secreta das notificações como client_secret.

Obter um token de acesso

Para obter um token, envie uma requisição HTTP POST para:

/oauth2/token

Cabeçalho de autenticação

O cabeçalho deve conter o client_id e o client_secret no formato Basic Auth:

Authorization: Basic Base64(client_id:client_secret)

A maioria dos clientes HTTP gera automaticamente a codificação Base64.

Corpo da requisição

Envie os parâmetros utilizando o formato application/x-www-form-urlencoded.

Parâmetro	Obrigatório	Descrição
username	Sim	Email do usuário cadastrado na Orkestral
password	Sim	Senha do usuário
grant_type	Sim	Deve possuir o valor password

Exemplo com cURL

curl --request POST \
  "${BASE_URL}/oauth2/token" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=${USER_EMAIL}" \
  --data-urlencode "password=${USER_PASSWORD}" \
  --data-urlencode "grant_type=password"

O parâmetro --user do cURL cria automaticamente o cabeçalho Basic Auth.

cuidado

Não coloque credenciais diretamente no código-fonte ou em scripts versionados.

Resposta de sucesso

Quando as credenciais são válidas, a API retorna uma resposta semelhante a:

{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Campos da resposta

Campo	Descrição
access_token	JWT utilizado para acessar os recursos protegidos
refresh_token	Token usado para renovar o acesso sem reenviar a senha
token_type	Tipo do token, atualmente Bearer
expires_in	Tempo de validade do access token, em segundos

Validade dos tokens

A configuração atual utiliza os seguintes períodos:

Ambiente	Access token
Homologação	30 minutos
Produção	15 minutos

O refresh token possui validade de 24 horas.

O cliente não deve assumir um valor fixo para o tempo de expiração. Sempre utilize o valor retornado no campo expires_in.

Utilizar o access token

Inclua o access token no cabeçalho Authorization de cada requisição protegida:

Authorization: Bearer access_token

Exemplo de criação de uma transação:

curl --request POST \
  "${BASE_URL}/transaction/payin/${MERCHANT_ID}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "IP: ${CLIENT_IP}" \
  --data @transaction.json

O MERCHANT_ID informado na URL deve corresponder ao merchant presente no token. Uma tentativa de operar em nome de outro merchant será rejeitada.

Renovar o access token

Quando o access token expirar, utilize o refresh token para obter um novo conjunto de tokens.

Envie uma nova requisição HTTP POST para:

/oauth2/token

Corpo da renovação

Parâmetro	Obrigatório	Descrição
grant_type	Sim	Deve possuir o valor refresh_token
refresh_token	Sim	Token retornado na autenticação anterior

Exemplo com cURL

curl --request POST \
  "${BASE_URL}/oauth2/token" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}"

A renovação retorna um novo access token e um novo refresh token.

Após uma renovação bem-sucedida:

• substitua o access token anterior;
• armazene o novo refresh token retornado;
• atualize o tempo de expiração utilizando o novo expires_in.

Tratamento recomendado para token expirado

Ao receber uma resposta 401 Unauthorized:

1. Verifique se existe um refresh token disponível.
2. Realize uma única tentativa de renovação.
3. Se a renovação for bem-sucedida, repita a requisição original com o novo access token.
4. Se a renovação falhar, interrompa a sessão e solicite uma nova autenticação.

Evite ciclos infinitos de renovação e repetição da requisição.

Códigos de resposta

Endpoint de autenticação

Status	Descrição
200 OK	Token gerado ou renovado com sucesso
400 Bad Request	Parâmetro ausente, requisição inválida ou email/senha incorretos
401 Unauthorized	client_id ou client_secret inválido
403 Forbidden	Usuário não ativado, conta bloqueada ou senha expirada

Recursos protegidos

Status	Descrição
401 Unauthorized	Token ausente, inválido, expirado ou pertencente a outro merchant
403 Forbidden	Usuário autenticado sem permissão para realizar a operação

Erros específicos de autenticação

Usuário não ativado

{
  "error": "user_not_activated",
  "message": "User not activated"
}

O usuário deve concluir a ativação da conta antes de se autenticar.

Conta temporariamente bloqueada

{
  "error": "account_temporarily_locked",
  "message": "Account temporarily locked"
}

Após dez tentativas inválidas dentro de quinze minutos, a conta é bloqueada temporariamente por trinta minutos.

Senha expirada

{
  "error": "password_expired",
  "message": "Password expired",
  "token": "token-para-alteracao-da-senha"
}

A senha do usuário expira após noventa dias.

O campo token dessa resposta é destinado ao processo de alteração da senha. Ele não deve ser utilizado como access token.

Encerramento da sessão

Ao encerrar uma sessão:

• remova o access token do armazenamento local;
• remova o refresh token;
• remova cookies e demais informações de sessão;
• não reutilize tokens armazenados anteriormente.

Se houver suspeita de comprometimento do client_secret, da senha ou dos tokens, interrompa a integração e acione o time responsável pela Orkestral.

Boas práticas de segurança

• Utilize sempre HTTPS.
• Nunca envie tokens ou credenciais em parâmetros da URL.
• Não coloque credenciais diretamente no código-fonte.
• Utilize um gerenciador de segredos.
• Não armazene tokens em logs.
• Não exponha o client_secret em aplicações frontend.
• Restrinja o acesso ao client_secret somente aos serviços responsáveis pela autenticação.
• Utilize o valor de expires_in para controlar a validade do token.
• Renove o token somente quando necessário.
• Não compartilhe tokens entre ambientes.
• Utilize credenciais diferentes para homologação e produção.
• Implemente alertas para tentativas repetidas de autenticação sem sucesso.
• Em caso de comprometimento, substitua as credenciais junto à Orkestral.