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.

Prepare following information:

FieldRequired?Description
App NameThe app's public name
TaglineMerchants should be able to understand the purpose of the app and the benefits from the tagline
App iconYour 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
CategoriesSolution Providers
CompatibilityAfterShip / AfterShip Shipping / Returns
Promotional videoDemonstrate 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 featuresHighlight three main features to attract merchants.
Images dimensions: 1600x1200
Title: 30 characters max
Description: 140 characters max
ScreenshotsProvide a collection of clear and well-cropped screenshots of your app to help merchants understand how your app works
Dimensions: 1600px x 900px
Detailed descriptionProvide details about how the app works, the features, and additional highlights.
Max 2800 characters
EmailSupport contact email address
Privacy policy URLIf 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 URLYour app‘s website
FAQ URLYour app‘s FAQ page URL
App URLYour app's main URL.
Redirect URLThe redirect URL used during the OAuth flow.
ScopeRequired 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.

Query ParametersDescription
productAfterShip product code to specify which product to use.
timestampUnix timestamp in millisecond
hmacSignature hash in HMAC-SHA256 algorithm

Example App URL Request

preparing...

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.

preparing...
Query ParametersDescription
client_idThe API key for the app.
productAfterShip product code. Allowed values: aftership postmen returns
redirect_uriThe destination URL after the merchant authorizes the app. The URL must be defined in your app as the allowed redirection URL.
response_typeOAuth authorizataion grant type. Allowed value: code
scopeA 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
stateA 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

preparing...

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

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

Query ParametersDescription
codeAuthorization code
timestampUnix timestamp in millisecond
hmacHMAC signature signed by AfterShip

Example Redirect URL Request

preparing...

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
  1. Extract the query string from the redirect URL request.
preparing...
  1. Exclude the hmac parameter
preparing...
  1. Reorder all the query parameters in alphabetical orders, if required.

  2. Calculate the hash with the HMAC-SHA256 algorithm, with your API secret as the secret key.

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

MethodURL
POSThttps://apps.aftership.com/oauth/token
Body ParametersDescription
codeAuthorization code
client_idThe API key of the app
client_secretThe API secret of the app
grant_typeGrant type. Allowed value: authorization_code
Response valueTypeDescription
access_tokenStringAPI access token for accessing merchant’s data. It will expire in 30 days. Once expired, you need to refresh the access token.
refresh_tokenStringFor refreshing the access token. It will expire in 90 days. If the refresh token is expired, the merchant needs to be reauthorized.
expires_inIntegerThe number of seconds until the access token expires.
token_typeStringToken type. The value would be Bearer
Response valueDescriptionRequired
errorError code. Check here for detail.
error_descriptionDetailed error description. Check here for detail.
error_urlError URL. Check here for detail.

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.

Header NameDescription
as-access-tokenThe OAuth 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.

MethodURL
POSThttps://apps.aftership.com/oauth/token
Body ParametersDescription
refresh_tokenThe refresh token
client_idThe API key of the app
client_secretThe API secret of the app
grant_typeGrant type. Allowed value: refresh_token

The response would be same as Step (4).

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

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