OAuth

Your app cannot read Orderchamp data without authenticating first. It must get permission from a user before gaining access to any of the resources in the GraphQL API. This guide walks you through the authorization process, described in greater detail by the OAuth 2.0 specification (opens new window).

On this page

• Terminology
• The OAuth flow
• Step 1: Get client credentials
• Step 2: Ask for permission
• Step 3: Confirm installation
• Step 4: Making authenticated requests
• Verification
  • Process through the hash function
• Finish installation

Terminology

Before learning more about the details of the authorization process, make sure that you're familiar with some of the key terms used in this guide:

• Client: Any app that wants access to an account's data. A user must grant permission before the client can access any data.
• GraphQL API: Orderchamps's GraphQL API, which the client can use to read and modify account data.
• Account: An Orderchamp account holder, usually a supplier. The user gives permission to a client to access account data through the GraphQL API.

The OAuth flow

Orderchamp uses OAuth 2.0's authorization code grant flow (opens new window) to issue access tokens on behalf of users.

Supplier	➡️	App	➡️	Orderchamp
Makes a request to install the app		Redirects to Orderchamp to load the OAuth grant screen		Displays required scopes and prompts the user to log in if required

1. The user makes a request to install the app.
2. The app redirects to Orderchamp to load the OAuth grant screen and requests the required scopes.
3. Orderchamp displays a prompt to receive authorization and prompts the user to login if required.
4. The user consents to the scopes and is redirected to the redirect_uri.
5. The app makes an access token request to Orderchamp including the client_id, client_secret, and code.
6. Orderchamp returns the access token.
7. The app uses the token to make requests to the Orderchamp GraphQL API.
8. Orderchamp returns the requested data.

Step 1: Get client credentials

You need to retrieve a CLIENT_ID and CLIENT_SECRET to identify the client during the authorization process. Please contact partners@orderchamp.com to get a key pair.

Step 2: Ask for permission

After the user clicks an install link, your app receives a GET request on the app URL path specified for your app. Requests to this route from a user that is logged into the Orderchamp backoffice include the account_d, timestamp, and signature query parameters.

Note

You need to verify the authenticity of these requests via the provided HMAC. For more information, see Verification.

Orderchamp displays a prompt to receive authorization from the user:

To show the prompt, redirect the user to the following URL with the query parameters defined below:

https://www.orderchamp.com/oauth/authorize?response_type=code&client_id={CLIENT_ID}&scope={SCOPE}&redirect_uri={APP_URL}

• {CLIENT_ID}: Your App's CLIENT_ID
• {SCOPE}: Comma separated list of scopes, for example: scope=account_read,products_read
• {APP_URL}: Redirect URL used as callback to your app

Step 3: Confirm installation

When the user clicks the Install button in the prompt, they're redirected to the client server as specified above. The authorization_code is passed in the confirmation redirect.

https://example.org/auth/callback/uri?account_id={account_id}&code={authorization_code}&state={state}&timestamp=1570536833&signature=2ea417b02d293a55ea28d22f06658815e359061b054e641a5f627ee81012ea5a

Note: All other query params will be appended if you had specified any in the App callback URL.

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

• The state is the same one that your app provided to Orderchamp during step two.
• The signature is valid. The HMAC is signed by Orderchamp as explained below, in Verification.

If all security checks pass, then you can exchange the access code for a permanent access token by sending a request to the OAuth access_token endpoint:

POST https://www.orderchamp.com/oauth/access_token

Make sure the following parameters are be provided in the request body:

{
  "grant_type": "authorization_code",
  "code": "{CODE}",
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}"
}

• {CODE}: The authorization code provided in the redirect
• {CLIENT_ID}: The API key for the app
• {CLIENT_SECRET}: The API secret key for the app

The server responds with an access token:

{
  "access_token": "dfa540127b8d0abb3b1cf1be93bdefbd35a50b7a",
  "token_type": "bearer",
  "scope": "account_read,orders_read,products_write"
}

The following values are returned:

• access_token: An API access token that can be used to access the account's data as long as the client is installed. Clients should store the token somewhere to make authenticated requests for a account's data.
• scope: The list of access scopes that were granted to the application and are associated with the access token. Due to the nature of OAuth, it's always possible for a merchant to change the requested scope in the URL during the authorize phase, so the application should ensure that all required scopes are granted before using the access token. If you requested both the read and write access scopes for a resource, then check only for the write access scope. The read access scope is omitted because it's implied by the write access scope. For example, if your request included scope=orders_read,orders_write, then check only for the orders_write scope.

Step 4: Making authenticated requests

After the client has obtained an API access token, it can make authenticated requests to the Graph API. These requests are accompanied with a bearer header Authorization: Bearer {ACCESS_TOKEN} where {ACCESS_TOKEN} is replaced with the permanent token.

Verification

Every request or redirect from Orderchamp to the client server includes a signature parameter that can be used to verify the authenticity of the request from Orderchamp. For each request, you must remove the signature entry from the query string and process it through an HMAC-SHA256 hash function.

By way of example, consider the following query string:

"code=ad670cac0bd678b587ad465acd46aacd&signature=2ea417b02d293a55ea28d22f06658815e359061b054e641a5f627ee81012ea5a&account_id=94949393&state=7657657&timestamp=1337178173"

Process through the hash function

You can process the string through an HMAC-SHA256 hash function using the secret key. The message is authentic if the generated hexdigest is equal to the value of the hmac parameter.

PHP Example

<?php
parse_str(
  "code=ad670cac0bd678b587ad465acd46aacd&signature=2ea417b02d293a55ea28d22f06658815e359061b054e641a5f627ee81012ea5a&account_id=94949393&state=7657657&timestamp=1337178173", 
  $payload
);

$signature = $payload['signature'];
unset($payload['signature']);

$calculated = hash_hmac('sha256', http_build_query($payload), CLIENT_SECRET);

hash_equals($calculated, $signature);
?>

Finish installation

After we have returned the user to your application and the installation has been finished, you need to return the user to the following url:
https://www.orderchamp.com/oauth/finish?client_id={your_app_client_id}