Getting Started - AfterShip Shipping API - AfterShip Docs

Getting Started

Public apps that are created in the Partner Dashboard must obtain authorization using the OAuth 2.0 specification to use AfterShip’s API resources.

This guide shows you how to authorize a public app using OAuth.

1. Create a public app

Prepare following information:

Field	Required?	Description
App Name	✔	The app's public name
Tagline	✔	Merchants should be able to understand the purpose of the app and the benefits from the tagline
App icon	✔	Your app icon helps users visually recognize your app in search results, the AfterShip admin, and other contexts. Must be a .jpg or .png Dimensions: 1200px by 1200px
Categories		Solution Providers
Compatibility	✔	AfterShip / AfterShip Shipping / Returns
Promotional video		Demonstrate the app’s features and benefits that can attract the merchant. Try to avoid screencasts showcasing the onboarding process or tutorial. Recommended duration: under 2 mins.
Key features		Highlight three main features to attract merchants. Images dimensions: 1600x1200 Title: 30 characters max Description: 140 characters max
Screenshots		Provide a collection of clear and well-cropped screenshots of your app to help merchants understand how your app works Dimensions: 1600px x 900px
Detailed description	✔	Provide details about how the app works, the features, and additional highlights. Max 2800 characters
Email	✔	Support contact email address
Privacy policy URL	✔	If your app deals with customer data, we strongly suggest that you have your privacy policy documented on your website. Please provide a URL to help merchants discover the steps you're taking to protect their data.
Website URL		Your app‘s website
FAQ URL		Your app‘s FAQ page URL
App URL	✔	Your app's main URL.
Redirect URL	✔	The redirect URL used during the OAuth flow.
Scope		Required permission scopes.

Before your app can access any merchant's data, the merchant has to grant permission to the app. The merchant grants permission when they install the app. When the merchant clicks the install button to initiate the installation process, the merchant's browser will be redirected to the App URL (Defined in Step (1)), with all the required parameters.

App URL Specification

Query Parameters	Description
product	AfterShip product code to specify which product to use.
timestamp	Unix timestamp in millisecond
hmac	Signature hash in HMAC-SHA256 algorithm

Example App URL Request

GET https://appurl.example.com/myapp?product=aftership&timestamp=1648014226847&hmac=9059a5bca4354bd703aeaebadc973ef45a61020dd07a262d9aa0ffbf3d477bad

When your app server receives the above request, the server should redirect the merchant's browser to the following AfterShip OAuth Server URL, with all required parameters.

AfterShip OAuth Server URL Specification

GET https://apps.aftership.com/oauth/authorize

Query Parameters	Description
client_id	The API key for the app.
product	AfterShip product code. Allowed values: aftership``postmen``returns
redirect_uri	The destination URL after the merchant authorizes the app. The URL must be defined in your app as the allowed redirection URL.
response_type	OAuth authorization grant type. Allowed value: `code`
scope	A comma-separated list of scopes. For example, to read postmen label and write postmen label, the value would be `postmen:label:read,postmen:label:write`
state	A unique random value generated for each authorization request. During the OAuth callback, your app needs to compare this value to the one you provided during authorization for security reasons. For more information, visit here.

Example AfterShip OAuth Server URL Request

GET https://apps.aftership.com/oauth/authorize?client_id=12dvefc079f6640d5891f07ef58rt4rop&scope=postmen:label:read,postmen:label:write&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&response_type=code&product=postmen&state=xyz

An installation permissions prompt would be displayed to the merchant to ask for the permission grant.

3. Confirming the installation

After the merchant grants the permission and confirms installing the app, the browser will be redirected to the Redirect URL (specified in Step (1)) together with the code.

Redirect URL Specification

Query Parameters	Description
code	Authorization code
timestamp	Unix timestamp in millisecond
hmac	HMAC signature signed by AfterShip

Example Redirect URL Request

https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz&timestamp=1648014226847&hmac=9059a5bca4354bd703aeaebadc973ef45a61020dd07a262d9aa0ffbf3d477bad

Validate the response

Before you continue, make sure that your app performs the following security checks. If any of the checks fail, your app must reject the request with an error and must not continue.

The state should be the same as you provided during Step 2.
Verify the payload ownership with hmac value.

Calculating the HMAC

Extract the query string from the redirect URL request.

code=SplxlOBeZQQYbYS6WxSbIA&state=xyz&timestamp=1648014226847&hmac=9059a5bca4354bd703aeaebadc973ef45a61020dd07a262d9aa0ffbf3d477bad

Exclude the hmac parameter.

code=SplxlOBeZQQYbYS6WxSbIA&state=xyz&timestamp=1648014226847

Reorder all the query parameters in alphabetical orders, if required.
Calculate the hash with the HMAC-SHA256 algorithm, with your API secret as the secret key.

4. Retrieve access token

After validating the response, you can exchange the access token with the authorization code.

Method	URL
POST	https://apps.aftership.com/oauth/token

Request Payload

Body Parameters	Description
code	Authorization code
client_id	The API key of the app
client_secret	The API secret of the app
grant_type	Grant type. Allowed value: `authorization_code`

Normal Response Payload

Response value	Type	Description
access_token	String	API access token for accessing merchant’s data. It will expire in 30 days. Once expired, you need to refresh the access token.
refresh_token	String	For refreshing the access token. It will expire in 90 days. If the refresh token is expired, the merchant needs to be reauthorized.
expires_in	Integer	The number of seconds until the access token expires.
token_type	String	Token type. The value would be `Bearer`

Error Response Payload

Response value	Description	Required
error	Error code. Check here for detail.
error_description	Detailed error description. Check here for detail.
error_url	Error URL. Check here for detail.	✔

5. Make authenticated requests

After you retrieve the access_token successfully, you can start accessing AfterShip product APIs with it. These requests are accompanied by a header as-access-token, and the value would be the access_token.

Required Headers

Header Name	Description
as-access-token	The OAuth access token.

6. Refresh the access token

The access token will expire after 30 days. You need to refresh the access token with the refresh token by the following endpoint.

Request Payload

Body Parameters	Description
refresh_token	The refresh token
client_id	The API key of the app
client_secret	The API secret of the app
grant_type	Grant type. Allowed value: `refresh_token`

The response would be same as Step (4).

7. Update the granted scopes

If you want to update the granted scopes after the merchant authenticates the app installation, please follow this flow:

Update your app server's code to include the newly granted scopes.
The merchant will go to the product app's page and click on the apps.
The merchant will be redirected to the App URL (specified in Step (1)) and then to the AfterShip OAuth Server URL.
As the granted scopes change, AfterShip will display it to the merchant again to seek permission.
The merchant agrees and grants the permission, and the flow would be the same from Step (3).