Obtain authentication token
STEP 1: Routing to your install URL
Purpose:
- Initiates the installation and authorization process for your application within the RETM marketplace.
Endpoint:
- Sandbox:
https://sandbox.retm.sa/integrations/authorized?client_id={application_client_id}
- Production:
https://retm.sa/integrations/authorized?client_id={application_client_id}
Endpoint:
GET
Authentication
- None required
Request Parameters:
- client_id (required, string): Your application's client ID provided by RETM.
:::info
You can have data related to the merchant returned to your endpoint once the access is granted by simply sending a URL parameters with the STEP 1, for example:https://retm.sa/integrations/authorized?client_id={application_client_id}&token=12345&status=1
The token and status will be sent within data key in the success callback in STEP 2.
:::
Response:
- Redirects the user to your specified installation endpoint.
Additional Information:
- Your application's installation endpoint should:
- Authenticate the user (if necessary).
- Obtain an authorization code from RETM.
- Redirect the user to the access token endpoint (STEP 3).
- Optionally, retrieve and store the token and status parameters.
STEP 2: Granting access
Purpose:
- Allows the user to grant your application access to their RETM data.
Actions:
- User decides whether to grant access in a consent window.
- RETM sends a POST request to your success endpoint upon consent.
Success Endpoint:
- Example:
https://{your-end-point}/success
Request Body:
{
"code": "string", // Authorization code
"business_id": "string", // Merchant's business ID
"data": { // Optional parameters sent in STEP 1
// ...
}
}
STEP 3: Making the Request for Access Token
Purpose:
Exchanges the authorization code for an access token.
Endpoint:
- Sandbox:
https://sandbox.retm.sa/api/oAuth/token
- Production:
https://{business_id}.retm.sa/api/oAuth/token
Method:
POST
Request Body:
{
"code": "YOUR_AUTHORIZATION_CODE",
"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}
Response:
{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "YOUR_REFRESH_TOKEN"
}
Additional Notes:
- Use the
business_id
as a subdomain for future API requests. - Handle potential errors gracefully (e.g., invalid authorization code).
- Consider security best practices (e.g., secure storage of tokens).
Modified at 11 days ago