Authentication

API credentials are available through your ShopWired account by navigating to Account > API keys.

• Keep your API credentials safe and secure
• Only provide them to trusted third parties
• If you suspect your credentials have been compromised, generate new API credentials immediately by selecting the generate new API credentials option

The external ShopWired app platform allows apps to:

• Ask for API access
• Be embedded inside ShopWired

Main properties of an external app:

• Name – This will appear in various places throughout the ShopWired account
• Main URL – The URL ShopWired will use to communicate with the app
• Additional URLs – These can be used as OAuth redirect URIs

After the app is created, the following credentials will be provided:

• Client ID – Used for initiating the OAuth flow and accessing the app inside ShopWired
• Client Secret – Used in the OAuth flow; must be kept secret
• Signature Secret – Used for signing requests; must be kept secret

Read more about creating apps for ShopWired.

OAuth is used to request API access

https://admin.myshopwired.uk/oauth/authorize?client_id=A&redirect_uri=B&scope=C&state=D

• client_id is provided by ShopWired
• redirect_uri is where the user is taken if they approve (must match the URL set when creating the app)
• scope is a comma-separated list of required API permissions
• state is a random string to prevent CSRF attacks

When the user authorises the request, they are redirected to redirect_uri with:

• code – Used to generate an access token
• state – Should match your original request
• signature – Should be verified for authenticity

Use the /oauth/access-token endpoint to generate tokens. The required POST parameters are:

• code
• client_id
• client_secret
• redirect_uri

To refresh tokens:

• refresh_token
• client_id
• client_secret

When sending API requests, include the access token in the Authorization header:

Authorization: Bearer ACCESS_TOKEN

When an app requests OAuth access to the ShopWired API, it must specify which permissions (or scopes) it needs. Each permission corresponds to a particular set of actions or data within the API. During the installation or update of the app, ShopWired will prompt the user to approve or deny these permissions.

Below is a list of available API permissions. Each scope can be included in the scope query parameter of the authorisation URL, separated by commas. If an app tries to access a resource or perform an action requiring a permission that was not granted, the request will be denied.

Each request contains:

• signature
• business_id
• timestamp (Unix time)

install is sent when the app is first installed, uninstall is sent after the app is removed.

To verify signatures:

1. Remove signature from the query parameters
2. Sort the remaining parameters by key
3. Generate a query string (key=value&key=value...)
4. Create a HMAC-SHA256 digest with the signature secret
5. Compare the digest with signature

Reject invalid or stale requests (e.g., older than 30 seconds)

A JavaScript library is available at https://platform.ecommercedns.uk/embedded-app/js/app.js.

initialize should be called as soon as possible. All other methods should be used within the ready callback.