OAuth 2.0 Configuration

OAuth 2

An Integration Definition consists of three main components, which match the OAuth2.0 code-exchange flow. In order, they are:

  1. Authorization
  2. Request Token
  3. Refresh Token

Example Specification

import {
AuthenticationType,
AuthSpecification,
OrderSourceAppMetadata,
} from "@shipengine/connect-order-source-api";
export const AuthProcess: AuthSpecification = {
Identifier: {
AuthenticationType: AuthenticationType.OAuth,
IsSandbox: false,
},
authorization: {
url_template: "https://accounts.example.com/o/oauth2/v2/auth",
query_parameters: [
{
name: "client_id",
value: "{installation:client_id}",
},
{
name: "redirect_uri",
value: "{system:authorize_callback_url}",
},
{
name: "response_type",
value: "code",
},
{
name: "scope",
value: "https://www.exampleapis.com/auth/content",
},
{
name: "access_type",
value: "offline",
},
{
name: "prompt",
value: "consent",
},
],
nonce: null,
},
request_token: {
url_template: "https://oauth2.exampleapis.com/token",
method: "POST",
body: [
{
name: "redirect_uri",
value: "{system:authorize_callback_url}",
},
{
name: "code",
value: "{callback:code}",
},
{
name: "grant_type",
value: "authorization_code",
},
{
name: "client_id",
value: "{installation:client_id}",
},
{
name: "client_secret",
value: "{installation:client_secret}",
},
],
headers: [
{
name: "Content-Type",
value: "application/x-www-form-urlencoded",
},
],
query_parameters: [],
},
refresh_token: {
url_template: "https://oauth2.exampleapis.com/token",
method: "POST",
body: [
{
name: "client_secret",
value: "{installation:client_secret}",
},
{
name: "grant_type",
value: "refresh_token",
},
{
name: "client_id",
value: "{installation:client_id}",
},
{
name: "refresh_token",
value: "{result_token_response:refresh_token}",
},
],
headers: [
{
name: "Content-Type",
value: "application/x-www-form-urlencoded",
},
],
query_parameters: [],
},
advanced_configuration: [],
};
export const Metadata: OrderSourceAppMetadata = {
// DO NOT CHANGE THIS ID AFTER PUBLISHING
Id: "bcce593b-dce3-4491-8722-a56e653c173f",
Name: "Example",
AuthProcess,
OrderSources: [Example],
};

Advanced Topics

  • Response Transformation (specify how responses from the two exchanges can be mapped into the the platform canonical model)
  • Connection Context (allows a response transformer to specify a collection of properties in connection_context)
  • Templating (substituting values in your configuration {installation:client_id}, etc...)