FAQ

Credentials

What is the difference between app credentials and merchant credentials?

These are two pairs of client_id and client_secret with completely different purposes:

	App credentials	Merchant credentials
Obtained from	Developer dashboard, when creating the app	Returned by /app/client/generate
Used for	Installation flow only	Transactional operations (customers, orders, payments)
How many exist	1 pair per app	1 pair per merchant that installed the app

Both use the same authentication endpoint (POST /oauth2/token), but the generated token will have different permissions. If you receive 401 when creating customers or orders, you are likely using the app credentials instead of the merchant credentials.

See the authentication guide for more details.

Can I use app credentials to create orders?

No. App credentials (client_id and client_secret obtained when creating the application) are used exclusively for the installation flow. To create customers, orders, and payments, you need the merchant credentials, which are generated at the end of the installation flow via POST /app/client/generate.

Authentication and tokens

What is the JWT token's validity period?

The API access token (JWT) is valid for 1 hour.

The 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.

What should I do when a 403 error occurs on the /oauth2/token route?

This error occurs when the call is being made to the wrong endpoint. The authentication route is separate from the API:

• Authentication: https://auth.sandboxappmax.com.br/oauth2/token
• API: https://api.sandboxappmax.com.br

Correct example:

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

I received a 401 when calling the API. What could it be?

The most common causes of 401 errors:

1. Wrong credentials: you are using app credentials instead of merchant credentials (or vice versa).
2. Expired token: the JWT token is valid for 1 hour. Generate a new one with the same credentials.
3. App token on transactional route: if you are calling customer, order, or payment routes, use the token generated with the merchant credentials.

See the common errors table for quick diagnosis.

What should I do when a 401 error occurs when creating a customer?

Check:

1. Whether the token is valid and not expired.
2. Whether the token was generated with the merchant credentials (not the app credentials) after the installation process.

App installation

What should I do when a 500 error occurs during app authentication?

This error usually happens when the installation flow is not followed correctly, specifically when the redirect and authorization step is missing.

The correct flow is:

1. Obtain the app token: POST https://auth.sandboxappmax.com.br/oauth2/token
2. Generate the authorization hash: POST https://api.sandboxappmax.com.br/app/authorize
3. Redirect the user: https://breakingcode.sandboxappmax.com.br/appstore/integration/HASH
4. Generate the merchant credentials: POST https://api.sandboxappmax.com.br/app/client/generate

The error occurs when the redirect to the authorization step (step 3) is missing.

How does the integration identify the store performing the installation?

Identification occurs through the user's login on the external platform.

When clicking "Install", a token is generated via POST https://api.appmax.com.br/app/authorize. The merchant is redirected to https://admin.appmax.com.br/appstore/integration/TOKEN_GERADO, where they enter the store name and select the company registered with Appmax.

After authorization, the hash is used to generate credentials via POST https://api.appmax.com.br/app/client/generate.

Note: The hash can only be used once, but the generated credentials are valid indefinitely until the app is uninstalled.

What is the difference between external_key and external_id?

Field	Who defines it	Usage	Can repeat?
external_key	External platform / merchant's system	Identify the origin of the installation	Yes
external_id	Generated by the integrator on the validation URL health check	UUID that binds the installation to the store; later used as external-id on CDN calls	No

They cannot be the same, as each field has a distinct purpose:

• external_key: identifies the origin in the platform/client context.
• external_id: confirmation of the app installation.

For the use of external_id after installation (header external-id on CDN calls, parameter of AppmaxScripts.init), see external-id.

Webhooks

What are the webhook errors and their meanings?

Code	Cause
502	Webhook URL registered incorrectly