All public endpoints require that an API key is supplied in the request. Each key is scoped to one retailer account in OrderSync and will only allow you to pull Order Status data for the retailer the key was created for.
The API key must be added to the X-API-Key header of the request:
curl
-H "X-API-Key: pk_live_your_key_here"
Creating an API Key
Currently, the only way to create an API key is using the OrderSync web app. You can create as many API keys for your retailer account as you'd like and can revoke any keys that have been created.
Follow these steps to create a key:
Log in to your OrderSync account at https://app.withordersync.com
Navigate to 'Settings' by clicking on your user avatar image and selecting 'Settings' from the menu
On the 'Settings' page, you must select 'API Keys' from the side navigation bar
NOTE: In order for the API Keys navigation link to appear, your user account must be designated as an 'admin' for your retailer.
To create a key, select 'New API Key'. You will be prompted to enter a name for your API key.
Once your key is created, you will be shown your key and given an opportunity to copy it to the clipboard.
Warning: You will only be shown your key once. Always keep it in a secure location and never commit it to any repo. If you have lost your key you will not be able to view it again and must create a new key.
API keys begin with a prefix which you can use to identify them, for instance:
pk_live_QuD_jk0u
NOTE: As of now, there is no way to make updates to any Orders or Order Status records via an API key. Therefore, all keys will be automatically set with a "read" scope only, which cannot be changed.
Revoking an API Key
Revoking a key is as easy as browsing to the 'API Keys' section of the 'Settings' page and clicking the 'Revoke' button next to the key you want to revoke.
Any key that is revoked will disappear and can never be used again to authenticate an API request.
Using your API Key
Here is an example of making a request using your API key:
curl "https://api.withordersync.com/api/v1/orders/by-po/PO12345" \
-H "X-API-Key: pk_live_abcdefghijklmnopqrstuvwxyz123456"
If your key is valid, the request will be authenticated and you will receive a 200 status response with the data you requested.
If the key is missing, invalid, or revoked you will receive a `401 Unauthorized` response with an error payload (see Errors):
json
{
"statusCode": 401,
"message": "API key is required. Provide it via the X-API-Key header."
}