The Client API is an OpenChannel API that is aimed to dramatically reduce the time and cost required when building your own marketplace, partner portal or integrating aspects into your existing website or application. This is especially beneficial for teams using a JamStack approach with Javascript front ends like React, Angular or Vue.

Our OpenChannel Client API is a proxy that sits on top of our existing API and takes on the added responsibilities of authentication, authorization and data validation. In short, it’s designed to be the backend API for your React, Angular or Vue based app marketplace or partner portal.

This means that you don’t need to create a server side application to communicate with the OpenChannel API. Instead, the new API also handles authentication and authorization of end users at the client side which allows your users to log in using your own SSO tokens or OpenChannel provided tokens. In addition, the new API makes it very easy to call the OpenChannel API from within your product in or website.

Unlike our traditional Market API our Client API is built to handle the context of the logged in user. Instead of authenticating with a general purpose API key, the OAuth access token obtained by the logged in user is passed to the Client API.

This guide will focus on helping you get familiar with making calls to the Client API using Postman. We’ve provided a Postman collection for download that will help you get get started with making your first API calls.

Download Postman Collection

 

Getting Started

Let’s get started by making a few calls to the Client API but before we do, we’ll need to perform some setup. The Client API needs to know the origin URL so that it knows how to handle your requests. In order to configure your URL please setup a self hosted site. The origin URL is an important part of every request and is linked directly to your account. If the origin URL is incorrect then you’ll receive a 401 error.

Try calling a public endpoint

Not all Client API endpoints require authentication or CSRF tokens. You can list your public apps by calling the GET https://client-api.openchannel.io/v2/apps endpoint. You’ll only need to set the ‘Origin’ header to your site URL. If successful then you’ll see the list of apps as a response (or a count of 0 if you have no apps). If you receive a 401 error then that means that you are using the incorrect site URL.

Get a CSRF token

The first step to calling the Client API’s private endpoints will be to generate and store a new CSRF token. Call the GET https://client-api.openchannel.io/auth/csrf endpoint with your ‘Origin’ header set to your site URL.

Native vs External authentication

When setting up your self hosted site, authentication can be set as either Native (default) or External authentication. Native authentication uses our SSO identity provider that we setup for you. External authentication connects the Client API to your own SSO identity provider that you have helped us setup.

In order to find out which has been setup for your account call the GET https://client-api.openchannel.io/auth/config endpoint with your ‘Origin’ header set to your site URL. The response will indicate whether you have EXTERNAL or NATIVE authentication setup. This configuration endpoint is also useful for gathering login and logout details required for configuring your front end.

Get an access token using Native authentication

In order to get an access token for Native authentication call the POST https://client-api.openchannel.io/auth/native/token endpoint with your ‘Origin’ header set to your origin URL, the ‘X-XSRF-TOKEN’ token in the header and the ’email’ and ‘password’ of the logged in user in the body. This user’s account must first be created before they can login. 

Get an access token using Native authentication

In order to get an access token for Native authentication you’ll first need to login to your identity provider’s login page as a user. In order to get an idToken from your identity provider, you’ll need to follow the steps for implementing the authorization code flow:

Once you have the id token, call the POST https://client-api.openchannel.io/auth/external/token endpoint with your ‘Origin’ header set to your site URL, the ‘X-XSRF-TOKEN’ token in the header and the ‘idToken’ in the body.

Cross Site Request Forgery Token

For each user’s browser session in your application, retrieve a CSRF token. This token is important for securing the requests to the Client API endpoints and is passed in the header with the key “X-XSRF-TOKEN“. A new token is generated by calling the GET https://client-api.openchannel.io/auth/csrf endpoint. As a result, the response will return:

  • A header with key X-XSRF-TOKEN
  • A cookie with key XSRF-TOKEN

A CSRF token only needs to be generated once per browser session. If the user closes the browser window and returns to the site then the CSRF token will need to be re-generated. Once you have the CSRF token, set it in the header of each request to the Client API with key “X-XSRF-TOKEN”.

Tip: As a best practice, wait until you need a token. Just before you are about to make a POST/PUT/PATCH/DELETE call to the Client API check to see if you have a CSRF token in sessionStorage. If you don’t then generate and store a new one and proceed with your API call. Only non-GET endpoints require a CSRF token.

The following are the steps that you may want to follow in order to obtain, store and use CSRF in a Single Page Application: 

  1. CSRF token initialization: Send GET request to GET https://client-api.openchannel.io/auth/csrf
  2. CSRF Extraction: Get value of the response header ‘X-CSRF-TOKEN’ received in the response.
  3. CSRF Storage: Store CSRF token in sessionStorage
  4. CSRF Interceptor: Use an interceptor to put this token value into the header of POST/PUT/PATCH/DELETE request with the key ‘X-CSRF-TOKEN’.

Client API Authentication

The Client API uses access tokens for authenticating client requests. If you have OpenChannel Native authentication configured then an access token can be generated by providing the email and password directly to the POST https://client-api.openchannel.io/auth/native/token endpoint. If you have External authentication configured then an access token can be generated by providing the idToken returned by your identity provider to the POST https://client-api.openchannel.io/auth/external/token endpoint.

A refresh token can be used to generate new access tokens. A new access token can be generated by providing the refresh token to the POST /auth/refresh endpoint.

Calling the Client API

Besides the authentication method there is no much difference between the existing OpenChannel API and the new Client API. The responses are the same, the object model is the same, the request parameters are mostly the same. However, there are a few notable differences. When calling the Client API please refer to the API documentation here.

Some API endpoints are not available in the Client API. Also, endpoints with userId, userAccountId, developerId or developerAccountId as parameters ignore any value passed in and use the values that are in the access token. This ensures that an end users or developers cannot perform actions based on other users.

Private Endpoints

Below are the API endpoints which require a user to be logged authenticated but are slightly different than the Market API:

Pubic Endpoints

Below are the API endpoints which do not require authentication:

Endpoints Not Available

Below are endpoints that are not available in the Client API.

  • GET /v2/developers
  • POST /v2/developers/{developerId}
  • DELETE /v2/developers/{developerId}
  • GET /v2/developerAccounts
  • POST /v2/developerAccounts/{developerAccountId}
  • DELETE /v2/developerAccounts/{developerAccountId}
  • GET /v2/users
  • POST /v2/users/{userId}
  • DELETE /v2/users/{userId}
  • GET /v2/userAccounts
  • POST /v2/userAccounts/{userAccountId}
  • DELETE /v2/userAccounts/{userAccountId}
  • POST/v2/stats/increment/{field}
  • GET /v2/files
  • POST /v2/ownership/install
  • POST /v2/ownership/uninstall/{ownershipId}
  • POST /v2/ownership/{ownershipId}
  • PATCH /v2/ownership/{ownershipId}
  • Any /v2/transactions endpoint
  • Any /v2/custom-gateway endpoint
  • Any /v2/stripe-gateway endpoint