Setup OAuth Authentication

Learn how to use the OAuth 2.0 standard to generate access tokens to interact with the Pine API.

You must set up an OAuth integration workflow if you're building an integration to access other people's data. After you complete the following steps, you can use your access token to interact with the API on behalf of that user.

Create a public application

As outlined earlier, you'll first need to create an OAuth application with the public workflow. Selecting that workflow will reveal additional inputs:

• Organization name - This is the name of the organization that will show up during installation.

• Organization URL - If users install your integration from the Pine user interface, they will be navigated to this URL.

• OAuth Callback URLs - This is an allowlist of URLs to which we'll redirect the user after they approve your integration.

• Publish application - Enabling this checkbox will make your integration visible to other Pine users.

Redirect user installation requests to Pine

You'll need to redirect your users to the following URL for them to approve your application:

https://www.pinecards.app/oauth/authorize?client_id=_&redirect_uri=_&state=_

Please populate the query parameters as appropriate for your application.

Parameter	Description
client_id	The client identifier for your application. Retrievable from your application settings.
redirect_uri	The URL we will redirect the user to when the user has authorized your application.
state	A session string which we will return appended to the redirect_uri. This is useful for mitigating CSRF attacks.

Handle the redirect URLs for users who have approved your application

Your users will be presented with the permissions that your application is requesting. If the user approves this request, we will redirect them back to your application via one of your supplied redirect_uris:

 https://yourapp.com/oauth/callback?code=_&state=_

We will populate the URL with the following query parameters:

Parameter	Description
code	The authorization code that you'll exchange for an access token. Expires after 5 minutes.
state	The same state that you supplied from the previous step.

Exchange your authorization code for an access token

Using the code from the previous step, make a POST request to the following endpoint to retrieve your access token:

https://www.api.pinecards.app/oauth/token

Supply the following parameters as part of the body of your request:

Parameter	Description
code	The authorization code from the previous step.
client_secret	The client secret for your application. Retrievable from your application settings.

A successful request will return the following response with an access_token that you can now use to interact with Pine's API:

{
  "access_token": "eyJ...",
  "token_type": "Bearer"
}

Pine's server library provides an easy way to interact with the API in a type-safe manner.

Revoke an access token

You can revoke an access token by making a POST request to the following endpoint, with the access_token supplied in the body of your request:

https://api.pinecards.app/oauth/revoke

Parameter	Description
access_token	The access token that you'd like to revoke.

We'll return a status 200 if we're able to revoke your token. Otherwise, we'll return a status 401 if we cannot verify your token (e.g. expired after 5 minutes) or a status 400 if we cannot revoke the token (e.g. token was already revoked).