Authenticating with Vendorful

In order to read or write data to Vendorful programmatically, it is critical that there is an authentication step. To keep things simple, Vendorful uses OAuth2 as it is nearly ubiquitous and is used by essentially every large public API provider (Microsoft, Google, Amazon, Twitter, Facebook) in some way. Consequently, there are free off-the-shelf OAuth2 libraries written in every popular programming language.

Core documentation on authenticating with Vendorful can be found here: https://api.vendorful.com/auth/index.html.

Who can create tokens?

Authentication tokens can be created by valid users, i.e., users who have active accounts in Vendorful. During the development process, it is typically easiest to use a user account. Bear in mind that, once authenticated, a user may or may not be able to programmatically access parts of Vendorful based on the user's permissions as configured in the application. Please make sure that if you are attempting to read or write data as a particular user that the user has the appropriate permissions to do so.

Most integrations will involve connecting Vendorful to another system like an ERP. To ensure that audit trails in Vendorful properly reflect "who" made changes in Vendorful, you will likely want to authenticate as the other system. As this is done during the authentication process, this change can be made in the end.

How long does a token remain valid?

A authentication token will expire roughly every two hours, meaning that you would only need to generate the token once every couple of hours (check the expires_in of the token on creation). For example, if you ran an hourly job to sync data, you would only have to create the token once every time the job starts, provided the current job completes before the next one starts.

Can you show me some code?

We have published some example code in Javascript at Github. Here is how you would authenticate as a user:

const TOKEN_ENDPOINT = "https://api.vendorful.com/auth/v1/token";

async function createPasswordToken(username, password) {
  const response = await fetch(TOKEN_ENDPOINT, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      grant_type: "password",
      username: username,
      password: password,
    }),
  });
  return await response.json();
}

Here's how you can authenticate as the client (i.e.,the calling application) while also keeping track of the specific user in the Vendorful audit history:

const TOKEN_ENDPOINT = "https://api.vendorful.com/auth/v1/token";
async function createToken(id, secret, username) {
  const params = {
    grant_type: "client_credentials",
    client_id: id, // Contact Vendorful support to get this configured
    client_secret: secret, // Contact Vendorful support to get this configured
  };
  if (username) params.username = username; // if the username passed in matches a Vendorful user in
                                           //  the organization, it will record it in the audit history
  const response = await fetch(TOKEN_ENDPOINT, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(params),
  });
  return await response.json();
}