npm package: @openverifiable/logto-connector-patreon
Description: Patreon OAuth connector for LogTo
Author: OpenVerifiable
Latest version: 1.0.0

# Patreon OAuth connector for LogTo

## ℹ️ Overview

This NPM package is [a custom OAuth connector designed for LogTo](https://docs.logto.io/docs/recipes/configure-connectors/create-your-connector/) for use with [Patreon](https://www.patreon.com/). [LogTo](https://logto.io/) is [an open-source identity management software](https://docs.logto.io/) with out-of-the-box support for many social connectors, and allows custom connectors to be created.

## 🛠️ Configuration

Once you've added this custom connector to LogTo (see *Developer Guide* below), you need to configure your connector following these steps:

### Step 1: Register Your Client

1. Sign up on [Patreon.com](https://www.patreon.com/) and create a creator account (required for OAuth)
2. Go to the [Clients & API Keys page](https://www.patreon.com/portal/registration/register-clients) to register your client application
3. When registering your client, you'll need to provide:
   - **App Name**: Your application name
   - **Redirect URIs**: The callback URL where users will be redirected after authorization (e.g., `https://yourapp.com/callback/patreon`)
   - **Description**: Brief description of your application

### Step 2: Configure in LogTo

After registering your client on Patreon, you'll receive:
- **Client ID**: Used to identify your application
- **Client Secret**: Used to authenticate your application (⚠️ Keep this secret!)

Copy these credentials and [configure them in your LogTo admin dashboard](https://docs.logto.io/docs/recipes/configure-connectors/social-connector/):

1. Go to your LogTo Admin Console
2. Navigate to Connectors → Social
3. Find and select the Patreon connector
4. Enter your:
   - **Patreon Client ID**
   - **Patreon Client Secret**
   - **Redirect URI** (must match what you registered on Patreon)
5. Save and enable the connector

### Important Security Notes

- **Never reveal your Client Secret**. If compromised, attackers could access your campaign info, patrons' profile info, email addresses, and pledge amounts.
- **Use HTTPS** for your redirect URI in production (http://localhost is allowed for development)
- If you suspect your secret has been compromised, regenerate it immediately on the Patreon Clients page

## 📋 Scopes

This connector requests the following scopes by default:
- `identity` - Access to basic user identity information
- `identity[email]` - Access to user's email address

These scopes are appropriate for user authentication and profile access. If you need additional scopes (like `pledges-to-me` or `my-campaign`), you would need to modify the connector's scope configuration.

## 🧑‍💻 Developer Guide

### Use with LogTo

To use this connector with LogTo, copy the NPM package contents into a new folder [under `packages/connectors/connectors-patreon` on a copy of the LogTo repository](https://github.com/logto-io/logto/tree/master/packages/connectors) or the LogTo Docker image.

You can build just this library using:

```bash
npm install
npm run build
```

### Token Refresh

Access tokens from Patreon expire after the duration specified in the `expires_in` field. The connector handles the initial OAuth flow, but if you need to refresh tokens, you can use the refresh token provided in the token response with a POST request to:

```
POST https://www.patreon.com/api/oauth2/token
```

With parameters:
- `grant_type=refresh_token`
- `refresh_token=<the user's refresh_token>`
- `client_id=<your client id>`
- `client_secret=<your client secret>`

## 📖 API Reference

This connector uses the Patreon OAuth 2.0 flow:

- **Authorization Endpoint**: `https://www.patreon.com/oauth2/authorize`
- **Token Exchange Endpoint**: `https://www.patreon.com/api/oauth2/token`
- **User Identity Endpoint**: `https://www.patreon.com/api/oauth2/v2/identity`

For more information, see the [Patreon OAuth documentation](https://docs.patreon.com/#oauth).

## 🔗 Resources

- [Patreon OAuth Documentation](https://docs.patreon.com/#oauth)
- [Patreon API Documentation](https://docs.patreon.com/)
- [LogTo Documentation](https://docs.logto.io/)
- [Register Patreon Client](https://www.patreon.com/portal/registration/register-clients)