OAuth Tokens

While API Keys are a quick and convenient way to make API requests from your third-party application in a machine-to-machine setting, sometimes you may want to authorize each user individually with a unique access token for each. This allows you to get the user context for specific users and require each user to authenticate with Pitchly before using Pitchly data in your application.
To get user-specific access tokens, you can use Pitchly's OAuth authorization code flow. OAuth is a global authorization standard for sharing data from one application to another. You can find an example of how this flow generally works here.
Below is a description of each step in the OAuth authorization code flow (and refresh token flow).

Initialize OAuth flow

This endpoint is triggered by the user opening this page in their browser with the following query parameters in the URL. The user will be presented with the option to authorize your app access to the user's Pitchly account. If approved, your app will receive an authorization code in return. In the next request, you will exchange that code for an actual access token via a server-side call.
Initialize OAuth flow

Exchange auth code for access token

Call this from your application's server side to exchange the authorization code returned by the previous request for an access token. You can then provide this access token in GraphQL API requests in the accessToken variable. When using a user-specific access token, replace all instances of secretKey in your GraphQL requests with accessToken, and provide your access token within it.
Do not call this endpoint from the client side, since the request contains your application's secret key. You should never make your secret key accessible client side.
Exchange authorization code for access token

Refresh access token (optional)

This step is optional and only applies if you wish to continue making API calls to Pitchly while the user is offline, or if you would like to continue making API requests without sending the user back through the OAuth flow after the token expires in 2 hours.
Whenever you receive a token-invalid error from a GraphQL API request, call this endpoint to get a new access token and retry the request. You will need a refresh token either from the previous request or from the result following this request.
While refresh tokens do not expire over time, they do expire as soon as they're used. If you wish to refresh access tokens, we recommend storing the refresh token in your database until it is ready to be used, and once exchanged, swap it with the new refresh token for the next refresh.
Refresh access token

Serverless flow

If you wish to use OAuth to acquire user-specific access tokens but don't have a sever side to exchange an authorization code for an access token, you can alternatively use the implicit flow to get an access token directly instead of an authorization code.
This method is not recommended if you do have a server side with which you can exchange authorization codes because it is slightly less secure than the authorization code flow described above. This method should only be used if you do not have a server side that can keep a secret, such as in the case of a single-page application (SPA) that does not have a server or a native mobile or desktop app.
To initiate the implicit flow, send the user to this endpoint:
Initialize implicit OAuth flow
If you do not have a server side, you will not be able to utilize refresh tokens to generate new access tokens once they expire because a secret cannot be kept. Instead, you will need to send the user back through this OAuth flow after the access token expires, so you can receive a new access token. By default, access tokens expire after 2 hours.
In future versions of Pitchly, you will not need to forward the user back through the OAuth flow to refresh access tokens on public clients (such as SPAs). Future versions of Pitchly will instead recommend always using the authorization code flow with PKCE (a new standard for generating dynamic secrets for a public client), which will allow you to exchange an auth code for an access token and refresh token entirely client side using a dynamic secret instead of a fixed secret which we use today.