# Getting Started

Public apps that are created in the Partner Dashboard must obtain authorization using the [OAuth 2.0 specification](https://tools.ietf.org/html/rfc6749) to use AfterShip’s API resources.

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

## [1. Create a public app](/content/docs/shipping/quickstart/authentication/oauth/getting-started#1-create-a-public-app/index.html)

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. <br>Must be a .jpg or .png <br>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. <br>Images dimensions: 1600x1200<br>Title: 30 characters max<br>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<br>Dimensions: 1600px x 900px                   |
| Detailed description | ✔       | Provide details about how the app works, the features, and additional highlights.<br>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.                                                                                                                                             |

## [2. Get the permission consent](/content/docs/shipping/quickstart/authentication/oauth/getting-started#2-get-the-permission-consent/index.html)

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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#app-url-specification/index.html)

| 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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#aftership-oauth-server-url-specification/index.html)

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](https://datatracker.ietf.org/doc/html/rfc6819#section-3.6). |

**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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#3-confirming-the-installation/index.html)

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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#redirect-url-specification/index.html)

| 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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#validate-the-response/index.html)

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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#calculating-the-hmac/index.html)

1. Extract the query string from the redirect URL request.

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

2. Exclude the `hmac` parameter.

code=SplxlOBeZQQYbYS6WxSbIA&state=xyz&timestamp=1648014226847

3. Reorder all the query parameters in alphabetical orders, if required.

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

## [4. Retrieve access token](/content/docs/shipping/quickstart/authentication/oauth/getting-started#4-retrieve-access-token/index.html)

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

| Method | URL                                              |
|--------|--------------------------------------------------|
| POST   | [https://apps.aftership.com/oauth/token](https://apps.aftership.com/oauth/token) |

#### [Request Payload](/content/docs/shipping/quickstart/authentication/oauth/getting-started#request-payload/index.html)

| 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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#normal-response-payload/index.html)

| 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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#error-response-payload/index.html)

| Response value      | Description                                                                             | Required |
|---------------------|-----------------------------------------------------------------------------------------|----------|
| error               | Error code. Check [here](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) for detail. |          |
| error_description    | Detailed error description. Check [here](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) for detail. |          |
| error_url          | Error URL. Check [here](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) for detail. | ✔        |

## [5. Make authenticated requests](/content/docs/shipping/quickstart/authentication/oauth/getting-started#5-make-authenticated-requests/index.html)

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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#required-headers/index.html)

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

## [6. Refresh the access token](/content/docs/shipping/quickstart/authentication/oauth/getting-started#6-refresh-the-access-token/index.html)

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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#request-payload-1/index.html)

| 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](/content/docs/shipping/quickstart/authentication/oauth/getting-started#7-update-the-granted-scopes/index.html)

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).