Long-Lived Tokens

For certain applications, continual access to data is necessary, even when its users are offline or not logged into Pitchly. One example of this is Pitchly's own Forms app. Forms, for example, must have access to a database's fields even when all users are logged out of the Pitchly platform in order to continue serving forms to outside visitors. To make this possible, particular tokens can be used to generate new access tokens after old ones have expired, without the need for user involvement.

Despite the name "Long-lived tokens," Pitchly actually uses the Refresh Token grant specified in the OAuth 2.0 standard to continuously generate new access tokens without user involvement. The advantage of refresh tokens over actual long-lived tokens is that they still expire, in the rare event one happens to leak.

Acquiring a refresh token

To get a refresh token, a regular access token must first be obtained via a user of your app (the Client) via the Pitchly platform. Once a regular access token is obtained, it can be sent to your server to attach a client_secret and client_id before making another server-side request to Pitchly to generate a new access token and refresh token. Save the new access token and refresh token on your server. Use the new access token on the client or server side, but keep the refresh token on the server side only. Do not reveal the refresh token to the client or any services besides your server and Pitchly's servers!

Using the refresh token

To generate a new access token once the old one expires without user involvement, you will use the refresh token stored on your server. Once you've determined that your current access token is no longer valid and you need a new one, send a request to Pitchly with the refresh token. Pitchly will return a new access token and a new refresh token, invalidating the old refresh token. Store the new refresh token on your server - without revealing it to the Client or any other party! - and continue to use the new access token normally until it expires again.

Refresh tokens do not expire over time, but they do expire each time they are exchanged for a new refresh token.

This is a high level overview of Pitchly Refresh Tokens for use in applications that require continuous data access on behalf of another organization, even when the application's users are not actively using Pitchly or your app. For specific details on Pitchly's OAuth endpoints, please contact us.