Authentication
Once you have a Client ID and Client Secret, the next step to making requests to the Pitchly API is to generate an access token that you can use to authenticate requests.
While your Client ID and Client Secret will generally remain the same for a long period of time, access tokens are usually short-lived. This makes your requests more secure.
Different types of access tokens can be generated for different types of use cases. Find your use case below and follow its instructions to learn how to generate an access token.
Accessing data in your own organization
This is the most common use case for customers who want to access their own data via Pitchly’s API. Generating an access token for this use case is also the most straightforward.
The access token in this case is a JSON Web Token (JWT) containing your Client ID and is signed with your Client Secret. Optionally, you may also set an expiry time on the token, specify which workspaces the token will provide access to, and specify which permissions the token will have.
Choose your specific use case below:
Accessing data on behalf of a user
This use case is the most common in situations where users log into your app, and you want to make API requests to Pitchly after the user has connected their Pitchly account.
In this section, you will learn how to authorize a user against Pitchly using OAuth to ultimately acquire an access token that can be used to make API requests against Pitchly.
Step #1: Redirect the user to our authorization page
Once the user is in your app, the first step is to redirect them to our authorization page. The URL will take the following format:
https://platform.pitchly.com/oauth/authorize?
response_type=code
&client_id=<CLIENT_ID>
&redirect_uri=<REDIRECT_URI>
&state=<STATE>
&code_challenge_method=S256
&code_challenge=<CODE_CHALLENGE>
Click on each section below to learn how to populate each variable:
Step #2: Exchange authorization code for an access token
After the user successfully authorizes your app to access their Pitchly data, we will redirect the user to your redirect_uri
with a code
in the URL query parameters. This code is only valid for a short time and must be exchanged for an access token.
To exchange this code for an access token, you will need to make a POST request to our token endpoint. See the details of that request below.
Exchange the authorization code for an access token
POST
https://platform.pitchly.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded
Request Body
grant_type*
String
"authorization_code"
code*
String
The code
you received
code_verifier*
String
The code_verifier
that was created in the process of generating the code_challenge
in step 1
client_id*
String
The client_id
of your app
client_secret*
String
The client_secret
of your app. This is required unless your app is a public client - i.e. an SPA, Mobile, or Desktop app that cannot keep a secret. More details.
scope
String
A space-delimited list of downscoped permissions you want the resulting access token to have. Note that you can only request the access token have fewer permissions than approved by the organization admin, not more.
workspace_ids
String
A space-delimited list of downscoped workspaces you want the resulting access token to have access to. Note that you can only request the access token have access to fewer workspaces than approved by the organization admin, not more.
Response
The response will include an access_token
, refresh_token
(which you can use to get a new access token once this one expires), how long the access token will be valid for in seconds via expires_in
, and a space-delimited list of permissions this access token has via scope
. Note that refresh tokens will remain valid until they are used.
{
"access_token": "plyu_BASyd6ePeMAR1RHVbpWOxU7Bda9ze9i-rFWuk-dEAZW",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "plyr_UQb-_2dHYpL7ExpHDkrLaTOrmUMYx27NYSDgeVNMdMo",
"scope": "records:create records:update"
}
Where you make this request from will depend on the capabilities of your app. Choose your app type below:
Step #3: Refresh access token after expiration (optional)
Access tokens are only valid for one hour. If you want to continue to access the user's Pitchly data after that time, you will need to get a new access token. You have two options to do that:
Redirect the user back through the OAuth flow again (starting from step 1).
Get a new access token using the
refresh_token
provided in the authorization code response.
The remainder of these instructions will focus on option #2.
Assuming you have held onto the refresh_token
returned in the authorization code response, you can acquire a new access token by making the following request.
Get a new access token using the refresh token
POST
https://platform.pitchly.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded
Request Body
grant_type*
String
"refresh_token"
refresh_token*
String
The stored refresh_token
client_id*
String
The client_id
of your app
client_secret*
String
The client_secret
of your app. This is required unless your app is a public client - i.e. an SPA, Mobile, or Desktop app that cannot keep a secret. More details.
scope
String
A space-delimited list of downscoped permissions you want the resulting access token to have. Note that you can only request the access token have fewer permissions than approved by the organization admin, not more.
workspace_ids
String
A space-delimited list of downscoped workspaces you want the resulting access token to have access to. Note that you can only request the access token have access to fewer workspaces than approved by the organization admin, not more.
Response
Response is identical to the authorization code response, except you will receive a new access_token
and a new refresh_token
. Note that the old refresh token will be immediately invalidated, so you will want to replace the old refresh token with this one, so that you can get a new access token again once this one expires. The new refresh token will remain valid up until it is used to get a new access token again.
{
"access_token": "plyu_EcH6g3bSVdjHtAAYuUOy4pbvWYIPxhDD97FBEmw-PT9",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "plyr_M5abea-_6JCE2kMRAHDjAWSISAbIXwWNEGwJlaUkbeq",
"scope": "records:create records:update"
}
Each time your access token expires, you can repeat this step again to get a new access token. If this request fails, you can redirect the user back through the OAuth flow (from step 1) to try to get an access token again. This can happen if the organization has uninstalled your app and it must be approved again.
Accessing data in an organization that has installed your app, on behalf of your app (instead of a user)
Most apps generally fall into one of the two use cases listed above. But if you’re trying to get data from an organization other than your own, the user flow carries one significant limitation: it requires a user.
What do you do if you want to access data in an organization that has installed your app but your app doesn’t have a user interface to allow users to sign in, or you simply want to get data from the organization at any time, regardless of whether a user has signed in recently?
Some examples may include:
An analytics app that emails you statistics on your account periodically.
An image tracker that notifies you of images in your tables that are copyrighted.
An integration to an outside system that syncs your data automatically.
This is where the client_credentials
grant can come in handy. To get an access token using this grant, make the following request.
Get an access token to an organization on behalf of your app
POST
https://platform.pitchly.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded
Request Body
grant_type*
String
"client_credentials"
organization_id*
String
The organization you want to access data from
client_id*
String
The client_id
of your app
client_secret*
String
The client_secret
of your app
scope
String
A space-delimited list of downscoped permissions you want the resulting access token to have. Note that you can only request the access token have fewer permissions than approved by the organization admin, not more.
workspace_ids
String
A space-delimited list of downscoped workspaces you want the resulting access token to have access to. Note that you can only request the access token have access to fewer workspaces than approved by the organization admin, not more.
Response
Unlike the response you receive for a user access token, this response will not include a refresh_token
. Once this access token expires, you can get a new one by simply making this request again.
{
"access_token": "plyi_T4_71q61OKQzyJMRwlF8LH6KQ5wfuqJIcruT6OS-_a9",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "records:create records:update"
}
Using the returned access token (which we call an “install access token”), you may now make API calls to the desired organization on behalf of your app itself instead of on behalf of a specific user.
Compared to user access tokens, note that install access tokens will differ in the following ways:
Install access tokens will have access to all workspaces the organization approves the app to access. User access tokens, in contrast, only have access to an intersection of workspaces the app has been approved access to + the workspaces the current user is a member of.
Install access tokens will not have access to anything that is private to a specific user, such as private views.
Keep these factors in mind if you plan to use a combination of user access tokens and install access tokens throughout your app, since one won't necessarily have access to the same resources as the other.
Next: Make API calls with GraphQL
Now that you have an access token, you can make API calls against our GraphQL API. Click the link below to learn how.
GraphQL APIResources
Permissions
Below are all possible permissions an app can have. The workspaces an app can access will depend on which workspaces the admin of the requested organization approves the app to access, as well as the type of access token that is generated.
records:create
Create records in workspaces
records:update
Update records in workspaces
records:delete
Delete records in workspaces
workspace_members:read
Read members of workspaces
teams:read
Read teams across the organization
documents:read
Read content and templates in the Elements app
table:create
Create a new table in a workspace
table:modify
Modify table dropdown field choices
rootTable:create
Create a table in the organization
Last updated
Was this helpful?