Authorization

ShipEngine Connect supports both Basic Auth and the OAuth 2.0 protocol for Order Apps. OAuth allows users to give your app permission to interact with your backend API on their behalf without having to supply their password. Instead, OAuth enables an end user to provide their credentials to a third party identity provider for authentication. This is much safer for the end user than providing their login credentials directly to your app. The access token can be revoked at any time without affecting any other applications or websites that have been given permission to act on behalf of the user.

Using OAuth 2.0 in Order Apps

You will provide a blank connection form in your Order App that will be displayed whenever a user selects your app from within one of our e-commerce applications. When the user clicks the Connect button, they will be redirected to a third party identity provider based on the workflow you have defined in your OAuth Config Definition file.

The user will then provide their credentials to the third party identity provider who will authenticate the user. Upon successful authentication, the identity provider will issue an access token for your app to use when making calls to your backend API. When a method in your Order App is called, it will receive a transaction object as the first parameter. You can then retrieve the OAuth access token from the transaction.session.auth.accessToken property.

Using Basic Auth in Order Apps

Specify the necessary authentication data in the connection form of your Order App. These fields will be included on the transaction object passed to the other methods of your app. If your form includes username, password, and/or api_key fields, they will be available via the transaction.session.auth object. All other fields will be attached to transaction.session.

Authorizing Using an API Key

If no OAuth Config is defined, and the fields associated with Basic Auth are not included in the connection form, we will assume the integration is using API Key Auth. In this case, you must specify that key inside the field api_key in the connection form. It can be referenced in the transaction.session.auth object.