Generating Access Tokens

After you have registered your App with Pitchly, you can now generate access tokens to get access to customer data. We will do so using the Pitchly JavaScript SDK.

This step assumes you have first registered your App with Pitchly.

Generating access tokens with Pitchly is not as scary as it sounds. Access tokens are essentially a unique string of jumbled characters and numbers that acts as a key to a particular organization's data. With one, you can do whatever your App has been authorized to do against the organization, limited to the scope and resources your App was given access.

Installation

If you are building a web app that has a frontend interface through which users will use your App, you don't need to handle the process of generating access tokens yourself. You can instead use our JavaScript SDK, which will generate and renew access tokens automatically for you.

To use the Pitchly JavaScript SDK, just embed the following into your <head> tag:

<script src="https://use.pitchly.com/sdk.js"></script>

Initialization & Callbacks

Initialize Pitchly wherever you're ready to start using Pitchly, probably after your page is loaded:

pitchly = new Pitchly({
  appId: "YOUR-APP-ID",
  onConnect: function(response) {
    if (response.error) { // error
      console.log(response.error);
      return;
    }
    // got access token, do stuff here...
    console.log(response.accessToken);
  }
});

The Pitchly function accepts several more optional parameters:

The onConnect callback will return a response object. Below is an example of a successful response:

{
  accessToken: "8KCYeiBx6idE9eXauYLeOnnDR2ySWmsm4uztyq0PGeX",
  accessTokenExpiresAt: "Sat Nov 24 2018 19:36:41 GMT-0600 (Central Standard Time)",
  organizationId: "fjzw5XGzqcXTH7PX7"
}

If you would like to convert the access token expiration date to a native JavaScript Date object, you can do so by passing the string directly to the new Date(...) function.

On error, the response will look something like:

{
  error: {
    name: "could-not-connect",
    reason: "Could not connect to Pitchly server.",
    code: 0 // the HTTP status code (will be 0 if network error)
  }
}

Methods

You can also perform certain actions against the instantiated Pitchly object:

To hide the filter when your App is initialized, for example, you would simply call:

pitchly.hideFilter()

To get the current organization and database, you would call:

pitchly.getOrganizationId();
pitchly.getDatabaseId();

You shouldn't normally need to call the latter methods to request information, since changes to the filter, row selections, etc. will automatically be pushed to you as they change via the onFilter, onSelection, etc. callbacks. The exception is requestUserId.

Any of the "request" type methods also accept an optional callback as an argument. When a callback is given, the callback will receive the result of the request after it has completed. It will be executed after any on___ callbacks.

Note that these references to pitchly when calling methods refers to the variable the Pitchly class is instantiated on, not the Pitchly class itself. They could just as easily be p.getDatabaseId() if Pitchly was instantiated to the variable p. Do not call methods from the Pitchly class itself.

Things to know about access tokens

We wouldn't feel right unless we let you know about a few things you should know about access tokens:

They expire after two hours (Luckily the SDK renews them automatically for you within 2-5 minutes of expiration. If internet connection is lost, it will retry every 5 seconds until a connection is made or until Pitchly returns an error. If a permanent error is returned, it's on you to call pitchly.generateAccessToken() to try again after the problem is resolved.)
Because access tokens renew automatically, you may get multiple calls to onConnect after a user has had your App open for more than two hours. If you cache the token anywhere, make sure you update it whenever you receive a new one.
Access tokens are scoped to the organization, not the database. We made it this way because it allows Apps to be more flexible when using data that spans across multiple databases, and it allows Apps to be presented to users in a variety of ways. Keep this in mind when designing your App's backend data structures, if you store any access tokens.
Even though access tokens are scoped to an organization, your App might not necessarily be. Often times, users install Apps on a specific database. Depending on your App, users may expect to see different saved information in your App, depending on which database they're in. Also keep this in mind when designing your data structures. (We recommend in this scenario centering information around "installs" instead of users or organizations.)
Access tokens may not always be new. They will often be re-used up to 10 minutes before their expiration.

Security checklist

Access tokens are very powerful, but with great power comes great responsibility. You should take the following factors into consideration when dealing with access tokens.

Always use HTTPS (not necessary for development, but this is necessary for any Apps in production)
If you store access tokens in a backend database, make sure access rights prevent anyone from being able to access other users' access tokens.
Make sure to request only the permissions you need for your App. This will limit potential harm if, for any reason, an access token becomes compromised.
To satisfy legal requirements, you must have a process in place to delete any and all user or company data you have received from Pitchly at the request of Pitchly. Please respect our clients.

Clients trust Pitchly to keep their data secure. For that reason, we have additional stringency requirements. These points simply serve as a reminder to follow best security practices and is by no means an exhaustive checklist. We will be adding more tips and pointers to this list over time.

Troubleshooting

If you're having any of the below issues, we may have possible solutions.

Q: Pitchly is telling me my access token is invalid or expired.

A: You may be using an old access token. Check whether your access token is coming from storage or a cache. You may also benefit from clearing your browser's history or trying to run your App in Incognito Mode in your browser.

Q: Pitchly is telling me I don't have permission to perform an action.

A: Every App is given permission to only do certain things on an organization in Pitchly. You may not have the permission to do that particular task. If you really do need this extra permission, contact us to request special permissions.

Q: Pitchly is telling me my App doesn't exist.

A: You probably haven't set the appId parameter to the correct value when initiating the Pitchly SDK. Make sure this is the same value you received when you registered your App with Pitchly. Also make sure it is your App ID and not your App's Secret. (Never put your App Secret in client-side code!)

Do you have a problem not listed here? Contact us and we'll try to help.

What if I'm not building a web app?

This guide covers how to generate access tokens using the Pitchly JavaScript SDK. However, if you can't use our SDK for any reason (such as because your App will not be user-facing or built on the web), you can still generate access tokens by using our REST API directly. In the big picture, our SDK is simply an abstraction that makes the process of working with our OAuth endpoints easier.

Our advanced guide will tell you what you need to know to work with our OAuth endpoints directly.

pageGenerating Access Tokens over HTTP

PreviousGetting Started NextUsing the GraphQL API

Last updated 3 years ago