Set Up Postman

The Miva Postman collection, Miva: JSON API: Authenticated, has a ready-made request for most JSON API functions, grouped in folders by area. It signs every request for you, so you can try a function and see its response before writing any signing code.

You need an API token with ProductList_Load_Query assigned, and its signing key if the token requires signed requests. See Create an API token.

Import the collection and environment#

1. Open the Miva Postman workspace.
2. Fork or import the Miva: JSON API: Authenticated collection and the Miva Environment environment into your own Postman workspace.
3. Select Miva Environment in the environment menu at the top right of Postman.

Fill in the environment#

Open the environment and set these 4 variables. They’re at the top of the list.

If your store uses a folder other than /mm5, change JSON_URL to match.

The rest of the environment holds sample IDs and codes the requests use, such as Product_Code, Order_ID and Customer_Login. Change them to records that exist in your store before running requests that read or change a specific record.

Send your first request#

1. Open the Getting Started folder at the top of the collection.
2. Open ProductList_Load_Query (first request) and click Send.
3. A successful response starts with "success": 1 and has one product under data. See Read the response.

The request has two saved examples, a success and a Function not assigned to token error, so you can see both shapes before you send anything.

If you get access_denied, check the message against Troubleshooting. The most common causes are a function not assigned to the token, an IP address not on the token’s list, and a signing key that doesn’t match the token.

How the collection signs requests#

A pre-request script on the collection runs before every request:

1. It reads API_Token and API_SigningKey from the environment.
2. It resolves the variables in the request body, including {{$timestamp}}, which fills in Miva_Request_Timestamp.
3. It writes the resolved body back to the request, so Postman sends exactly what was signed.
4. It calculates an HMAC-SHA256 signature over that body with the Base64-decoded signing key.
5. It sets X-Miva-API-Authorization to MIVA-HMAC-SHA256 <token>:<signature>. With API_SigningKey empty, it sends MIVA <token> instead.

These are the same steps your own code has to follow. Make a signed request with HMAC shows them in PHP, Node.js and Python.

Find a request#

The collection’s folders follow the same areas as the function reference. Common starting points:

Requests that insert, update or delete change real store data. Try them on a development store first.

Other Miva collections#

The Miva workspace has 2 more collections. Both use the same Miva Environment, and neither needs an API token.

Next steps#

• Make a signed request with HMAC
• Function reference