Authentication Process

Welcome to the authentication guide for accessing the Orkestral APIs.

Follow the instructions below to configure your credentials, obtain an access token, and make authenticated requests to the platform APIs.

Objective

Guide clients through obtaining, renewing, and using an access token to consume protected resources from the Orkestral APIs.

The current authentication process uses OAuth 2.0 with client credentials and the user's email and password.

Environments

Environment	Base URL
Testing	https://api-qas.orkestralpay.com.br
Production	https://api.orkestralpay.com

Use only the URL for the environment provided for your integration.

Prerequisites

Authentication requires:

• an active Orkestral account;
• a user linked to the merchant;
• the user's email and password;
• the client_id and client_secret provided by Orkestral during onboarding;
• an HTTPS connection.

Credentials used

The process uses two sets of credentials.

OAuth client credentials

The client credentials identify the application requesting the token:

• client_id;
• client_secret.

These credentials are sent in the Authorization header using Basic Auth.

User credentials

The user credentials identify the person being authenticated:

• username: email registered with Orkestral;
• password: the user's password.

Difference between the client secret and the Secret Key

The OAuth client_secret is not the same as the Secret Key displayed on the platform's Integration page.

• The client_secret authenticates the OAuth client and obtains tokens.
• The Secret Key on the Integration page validates the notification checksum.

warning

Do not use the notification Secret Key as the client_secret.

Obtain an access token

To obtain a token, send an HTTP POST request to:

/oauth2/token

Authentication header

The header must contain the client_id and client_secret using Basic Auth:

Authorization: Basic Base64(client_id:client_secret)

Most HTTP clients generate the Base64 encoding automatically.

Request body

Send the parameters as application/x-www-form-urlencoded.

Parameter	Required	Description
username	Yes	Email registered with Orkestral
password	Yes	User password
grant_type	Yes	Must have the value password

cURL example

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"

The cURL --user parameter automatically creates the Basic Auth header.

caution

Do not place credentials directly in source code or version-controlled scripts.

Successful response

When the credentials are valid, the API returns a response similar to:

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

Response fields

Field	Description
access_token	JWT used to access protected resources
refresh_token	Token used to renew access without resending the password
token_type	Token type, currently Bearer
expires_in	Access token lifetime in seconds

Token lifetime

The current configuration uses the following periods:

Environment	Access token
Testing	30 minutes
Production	15 minutes

The refresh token is valid for 24 hours.

The client must not assume a fixed expiration time. Always use the value returned in the expires_in field.

Use the access token

Include the access token in the Authorization header of every protected request:

Authorization: Bearer access_token

Example of creating a transaction:

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

The MERCHANT_ID in the URL must match the merchant in the token. An attempt to operate on behalf of another merchant will be rejected.

Renew the access token

When the access token expires, use the refresh token to obtain a new token set.

Send another HTTP POST request to:

/oauth2/token

Renewal request body

Parameter	Required	Description
grant_type	Yes	Must have the value refresh_token
refresh_token	Yes	Token returned by the previous authentication

cURL example

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}"

The renewal returns a new access token and a new refresh token.

After a successful renewal:

• replace the previous access token;
• store the new refresh token returned;
• update the expiration time using the new expires_in value.

Recommended handling for an expired token

When receiving a 401 Unauthorized response:

1. Check whether a refresh token is available.
2. Make a single renewal attempt.
3. If the renewal succeeds, repeat the original request with the new access token.
4. If the renewal fails, end the session and request a new authentication.

Avoid infinite renewal and request retry loops.

Response codes

Authentication endpoint

Status	Description
200 OK	Token generated or renewed successfully
400 Bad Request	Missing parameter, invalid request, or incorrect email/password
401 Unauthorized	Invalid client_id or client_secret
403 Forbidden	User not activated, account locked, or password expired

Protected resources

Status	Description
401 Unauthorized	Missing, invalid, expired token, or token for another merchant
403 Forbidden	Authenticated user without permission for the operation

Specific authentication errors

User not activated

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

The user must complete account activation before authenticating.

Account temporarily locked

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

After ten invalid attempts within fifteen minutes, the account is temporarily locked for thirty minutes.

Password expired

{
  "error": "password_expired",
  "message": "Password expired",
  "token": "password-change-token"
}

The user's password expires after ninety days.

The token field in this response is intended for the password change process. It must not be used as an access token.

Ending the session

When ending a session:

• remove the access token from local storage;
• remove the refresh token;
• remove cookies and other session information;
• do not reuse previously stored tokens.

If the client_secret, password, or tokens may have been compromised, stop the integration and contact the team responsible for Orkestral.

Security best practices

• Always use HTTPS.
• Never send tokens or credentials in URL parameters.
• Do not place credentials directly in source code.
• Use a secrets manager.
• Do not store tokens in logs.
• Do not expose the client_secret in frontend applications.
• Restrict access to the client_secret to services responsible for authentication.
• Use the expires_in value to track token validity.
• Renew the token only when necessary.
• Do not share tokens between environments.
• Use different credentials for testing and production.
• Implement alerts for repeated unsuccessful authentication attempts.
• If credentials are compromised, replace them with the Orkestral team.