API reference / Auth
Start seller authorization (302 to the consent page)
Starts seller authorization. Call it from your backend with the HMAC v3 headers and automatic redirect following disabled: a browser cannot attach those headers to a top-level navigation. The 302 Location is the unsigned consent page - open that URL in the seller browser. After the seller consents, MallPlus redirects the browser to the registered redirect_uri with code (one-time, 10 minutes), seller_id, and state when the authorize call supplied it. Those code and seller_id query values are exactly what POST /open/v1/auth/token requires; verify state against your own session first. Omitting client_id or redirect_uri returns 400 BAD_REQUEST naming the missing field, and a redirect_uri that is not the registered one returns REDIRECT_URL_MISMATCH.
Service Endpoint Seller token not required
| Environment | Base URL + Path |
|---|---|
| Production | https://open.mallplus.ph/open/v1/auth/authorize |
| Sandbox | https://sandbox.open.mallplus.ph/open/v1/auth/authorize |
Common Signing and Seller Headers
| Header | Type | Required | Rules | Description |
|---|---|---|---|---|
| X-MallPlus-Partner-Id | string | Yes | Issued client ID for the calling app. | Identifies the partner app whose secret signs the request. |
| X-MallPlus-Timestamp | integer | Yes | Unix timestamp in seconds; default acceptance window is 90 seconds. | Prevents replay outside the allowed signing window. |
| X-MallPlus-Signature-Version | string | Yes | Use 3 for HMAC v3. | Selects the request signing algorithm. |
| X-MallPlus-Nonce | string | Yes | 32-64 lowercase hexadecimal characters, unique per request. | Replay-protection nonce included in the v3 signing base string. |
| X-MallPlus-Signature | string | Yes | HMAC-SHA256 over timestamp, client ID, method, path, canonical query, body hash, and nonce. | Cryptographic proof that the request was signed with the app secret. |
| X-MallPlus-Access-Token | string | Conditional | Required when the operation says seller token required. | Seller OAuth access token returned by the authorization flow. |
| X-MallPlus-Seller-Id | string | Conditional | Required when X-MallPlus-Access-Token is required. | Seller ID bound to the seller OAuth token. |
Parameters
| Name | In | Type | Required | Rules | Description |
|---|---|---|---|---|---|
| client_id | query | string | Yes | - | Partner application client ID. |
| redirect_uri | query | string<uri> | Yes | Format: uri | Registered redirect URI that receives the authorization response. |
| state | query | string | No | Max length: 1024 | Optional opaque partner-generated value for CSRF binding. Echoed unchanged on the authorization or error redirect when supplied. |
Request Body
This operation has no JSON request body.
Response Parameters
Success status: HTTP 302
Redirect to the seller consent page. Location is the unsigned consent URL to open in the seller browser. After consent, the browser is redirected to the registered redirect_uri with code, seller_id, and state when supplied.
| Response header | Type | Description |
|---|---|---|
| Location | string<uri> | The seller consent page (unsigned). Carries client_id, redirect_uri, app_name, app_category, scopes, and state when supplied. |
The successful response has no JSON body; its result is in the response headers above.
Error Codes
| HTTP Status | Schema | Description |
|---|---|---|
| 400 | GetAuthAuthorizeError400Response | Validation error, or a missing/malformed required signing header (BAD_REQUEST) |
| 401 | PlatformError401Response | Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED) |
| 403 | PlatformError403Response | Forbidden — insufficient scope |
| 429 | PlatformError429Response | The partner or endpoint rate limit has been exceeded |
| 503 | PlatformError503Response | A required platform or upstream dependency is temporarily unavailable |
This operation can return these codes in error.code: REDIRECT_URL_MISMATCH
Any operation can also return the authentication, signing, scope, rate-limit and system codes listed in the Error code reference.
Request Example
# Sandbox: https://sandbox.open.mallplus.ph/open/v1/auth/authorize?client_id=example&redirect_uri=example
curl -X GET "https://open.mallplus.ph/open/v1/auth/authorize?client_id=example&redirect_uri=example" \
-H "X-MallPlus-Partner-Id: mp_partner_123" \
-H "X-MallPlus-Timestamp: 1786924800" \
-H "X-MallPlus-Signature-Version: 3" \
-H "X-MallPlus-Nonce: 4f8b9a0c4d5e6f708192a3b4c5d6e7f8" \
-H "X-MallPlus-Signature: <hex_hmac_sha256>"Response Example
HTTP/1.1 302 Found
Location: https://sandbox.open.mallplus.ph/seller/authorize?client_id=mp_xxxxxxxxxxxxxxxx&redirect_uri=https%3A%2F%2Fpartner.example.com%2Foauth%2Fcallback&app_name=Example+App&app_category=order_management&scopes=catalog%3Aread%2Corders%3Aread&state=xyz123