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:

Parameter

Type

Description

appId

string

The App ID you were given when registering your App.

onConnect

function

Called after an access token has been generated, or if an access token failed to generate. Passes back a response object. (See below)

onSelection

function

Called when the user has selected rows in the database. Passes back an array of selected row IDs.

onFilter

function

Called when the user updates the filter. Passes back the new filter object.

onShowSelected

function

Called when the user checks "Show Only Selected" in the database view. Passes back a boolean - true if checked, false otherwise.

debug

boolean

Pass true to print debugging information (including info on access tokens and errors) to the browser console. Defaults to false.

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:

Function

Description

getOrganizationId

Get the cached ID of the current organization (automatically retrieved on initialization)

getDatabaseId

Get the cached ID of the current database (automatically retrieved on initialization)

hideFilter

Hide the filter from view

showFilter

Show the filter in view

generateAccessToken

Forcibly request a new access token (not guaranteed to be new). Can pass an optional callback that will return the response, similar to onConnect. onConnect will still be called, just prior to the callback.

requestOrganizationId

Re-ask Pitchly for the current organization ID

requestDatabaseId

Re-ask Pitchly for the current database ID

requestSelections

Re-ask Pitchly for the current rows in the database that have been selected

requestFilter

Re-ask Pitchly for the current filter object

requestShowSelected

Re-ask Pitchly whether "Show Only Selected" is checked

requestUserId

Ask Pitchly for the current user ID

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.

Generating Access Tokens over HTTP

PreviousGetting Started NextUsing the GraphQL API

Last updated 4 years ago