API reference / Auth

Exchange authorization code for access + refresh tokens

POST/open/v1/auth/tokenScope: No data scope

Service Endpoint Seller token not required

Environment	Base URL + Path
Production	`https://open.mallplus.ph/open/v1/auth/token`
Sandbox	`https://sandbox.open.mallplus.ph/open/v1/auth/token`

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

This operation does not define path or query parameters in OpenAPI.

Request Body required

Field	Type	Required	Rules	Description
code	string	Yes	Min length: 1	One-time authorization code taken from the `code` query parameter of the consent redirect to your `redirect_uri`. Single-use and valid for 10 minutes.
client_id	string	Yes	Min length: 1	Partner application client ID.
seller_id	string	Yes	Min length: 1	Seller whose grant this code belongs to. Use the `seller_id` query parameter that the consent redirect delivered to your `redirect_uri` - do not send a sandbox Shop ID or a value of your own.

Response Parameters

Success status: HTTP 200

Field	Type	Rules	Description
success	boolean	-	Whether the request completed successfully.
data	TokenData	No additional properties	Response or event payload for this schema.
data.access_token	string	-	Seller-scoped access token.
data.refresh_token	string	-	Single-use refresh token. Rotated on every refresh.
data.expires_in	integer	-	Access-token TTL in seconds.
data.expires_at	string<date-time>	Format: date-time	Absolute access-token expiry timestamp in ISO-8601 UTC.
data.seller_id	string	-	Seller the token acts on.
data.seller_name	string	Nullable	Display name of the seller.
data.scopes	array<string>	-	OAuth scopes requested or granted.
data.scopes[]	string	-	-
meta	PaginationMeta	-	Response metadata, including pagination when the endpoint returns a list.
meta.page	integer	-	1-based page number represented by this response page. Offset paging only — omitted during a cursor walk.
meta.limit	integer	-	Maximum number of records returned in this response page.
meta.total	integer	-	Total number of records matching the request filters. Offset paging only — omitted during a cursor walk, where no total is computed.
meta.nextCursor	string	-	Opaque cursor for the next page of a keyset walk. Present only while walking by cursor and only while more rows may remain; its absence ends the walk. Pass it back unchanged as `cursor`.

Error Codes

HTTP Status	Schema	Description
400	PlatformError400Response	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
413	PlatformError413Response	The request body exceeds the endpoint payload limit
429	PlatformError429Response	The partner or endpoint rate limit has been exceeded
503	PlatformError503Response	A required platform or upstream dependency is temporarily unavailable

This operation does not declare its own error.code list. Any operation can 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/token
curl -X POST "https://open.mallplus.ph/open/v1/auth/token" \
  -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>" \
  -H "Content-Type: application/json" \
  --data '{
  "code": "example_code",
  "client_id": "client_id_123",
  "seller_id": "seller_id_123"
}'

Response Example

{
  "success": true,
  "data": {
    "access_token": "example_access_token",
    "refresh_token": "example_refresh_token",
    "expires_in": 14400,
    "expires_at": "2026-07-16T10:30:00.000Z",
    "seller_id": "seller_id_123",
    "seller_name": "example_seller_name",
    "scopes": [
      "example_scopes"
    ]
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "nextCursor": "eyJ0cyI6IjIwMjYtMDgtMTVUMDk6MzA6MDAuMDAwWiIsImlkIjoicGNhdF8xIn0"
  }
}