Authentication and authorization

Which credentials should I use?

I need to install the app on a store → use APP credentials (from the developer dashboard). Endpoints: /app/authorize, /app/client/generate.

I need to create a customer, order or payment → use MERCHANT credentials (returned at the end of the installation). Endpoints: /v1/customers, /v1/orders, /v1/payments/*.

I'm not sure → do you have a merchant who installed your app? If yes, use merchant credentials. If not, follow the installation flow first to obtain them.

Understanding the credentials

The Appmax API uses two pairs of credentials (client_id and client_secret). Both have the same format but serve completely different purposes. Confusing the two is the most common cause of integration errors.

App credentials

Field	Description
client_id	Your application's identifier in the Appstore
client_secret	Application secret key
Obtained from	Developer dashboard, when creating the application
Scope	Installation flow only (/app/authorize, /app/client/generate)
Validity	Permanent (as long as the app exists)

DANGER

App credentials do not allow creating customers, orders, or payments. If you receive a 401 error when calling the transactional API, you are likely using the wrong credentials.

Merchant credentials

Field	Description
client_id	Unique identifier for the app installation on that store
client_secret	Installation secret key
Obtained from	Returned at the end of the installation flow (/app/client/generate)
Scope	Transactional operations: customers, orders, payments, refunds
Validity	Permanent (until the app is uninstalled by the merchant)

TIP

For each merchant that installs your app, you receive a different pair of credentials. Store them securely, associated with the corresponding merchant.

Quick comparison

Aspect	App credentials	Merchant credentials
When generated	When creating the app in the dashboard	At the end of the installation flow
How many exist	1 pair per app	1 pair per merchant that installed the app
What they allow	Initiate installation, generate credentials	Create customers, orders, payments
Authentication endpoint	POST /oauth2/token	POST /oauth2/token (same endpoint)
Do they expire	No	No (until uninstallation)
Generated token expires in	1 hour	1 hour

WARNING

Both use the same endpoint (https://auth.appmax.com.br/oauth2/token) with the same request format. The only difference is which client_id and client_secret you send. The returned token will have different permissions depending on the credential used.

Visual flow

Common credential errors

Error	Likely cause	Solution
401 when creating customer/order	Using app credentials instead of merchant credentials	Use the credentials returned by /app/client/generate
401 when calling /app/authorize	Using merchant credentials instead of app credentials	Use the credentials from the developer dashboard
500 when calling /app/client/generate	Incomplete installation flow (missing redirect)	Follow all 4 steps of the installation flow in order
401 expired token	JWT token older than 1 hour	Generate a new token with the same credentials
403 on /oauth2/token	Wrong endpoint (using the API URL instead of auth)	Use https://auth.appmax.com.br/oauth2/token

Why don't we use refresh tokens?

The API adopts an authentication model without refresh tokens. This decision is based on the server-to-server communication architecture.

Detailed reasons

1. Server-to-server nature: communication occurs directly between servers in controlled, secure environments. This reduces the need for additional token renewal mechanisms.

2. Security and simplicity: short-lived tokens (1 hour) limit the usage window. In server-to-server environments where credentials are stored securely, this approach simplifies management.

3. Reduced complexity: eliminates secure refresh token storage, token rotation, and renewal logic.

4. Compliance with best practices: in server-to-server integrations, it is common to use short-lived access tokens with key-based authentication.

Obtaining the token

Authentication

Send the merchant credentials (for transactional operations) or the app credentials (for the installation flow).

Short-lived token

After authentication, a 1-hour access token is issued and must be used in all subsequent requests.

Token renewal

When the token expires, obtain a new one through the same initial authentication process.

Example with merchant credentials

curl --location 'https://auth.appmax.com.br/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=MERCHANT_CLIENT_ID' \
--data-urlencode 'client_secret=MERCHANT_CLIENT_SECRET'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Example with app credentials

curl --location 'https://auth.appmax.com.br/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=APP_CLIENT_ID' \
--data-urlencode 'client_secret=APP_CLIENT_SECRET'

WARNING

The merchant's client_id and client_secret are never changed. New ones can only be generated by performing new installations, and existing ones can only be deactivated by uninstalling the app.