# Setup OAuth Authentication

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](/basics/create-an-integration.md), 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_uri`s:

```
 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:

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

{% hint style="info" %}
Pine's [server library](/backend/server-library.md) provides an easy way to interact with the API in a type-safe manner.
{% endhint %}

### 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pinecards.app/basics/setup-oauth-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.