Skip to content

Commit 0cf12b4

Browse files
ekurutepeekurutepe
authored
OAuth docs (#1027)
1 parent 23fff1f commit 0cf12b4

File tree

5 files changed

+331
-13
lines changed

5 files changed

+331
-13
lines changed

‎docs/projects/authentication.md

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,47 @@ slug: authentication
55
excerpt: Manage your API keys to authenticate with RevenueCat
66
---
77

8-
RevenueCat authenticates requests from the RevenueCat SDK and the [REST API](/api-v2) using API keys.
8+
RevenueCat authenticates requests from the RevenueCat SDK and the [REST API](/api-v2) using API keys or OAuth tokens.
9+
10+
## Authentication Methods
11+
12+
### API Keys
913

1014
There are two types of API keys:
1115

1216
- **Public** API keys (also known as **SDK API keys** in the dashboard) are meant to make non-potent changes to subscribers, and must be used to [configure the SDK](/getting-started/configuring-sdk). Each app under a project is automatically provided with a public API key.
1317
- **Secret** API keys, prefixed `sk_`, should be kept confidential and only stored on your own servers. Your secret API keys can perform restricted API requests such as deleting subscribers and granting entitlements. Secret API keys are project-wide and can be created and revoked by project [Admins](/projects/collaborators).
1418

19+
### OAuth Tokens
20+
21+
For third-party integrations and tools, RevenueCat also supports OAuth 2.0 authentication using access tokens. OAuth tokens provide developer-level access (not tied to a specific project) and enable secure authorization for external applications.
22+
23+
- **Access tokens**, prefixed `atk_`, are obtained through the OAuth 2.0 flow and can be used to authenticate REST API v2 requests
24+
- OAuth tokens have scopes that determine what actions they can perform, and developers must grant explicit consent for each scope
25+
- See our [OAuth documentation](/projects/oauth-overview) for complete setup instructions
26+
27+
:::info OAuth vs API Keys
28+
OAuth tokens are developer-level credentials that can access all projects a developer owns or collaborates with, while API keys are project-specific. Use OAuth for third-party integrations and API keys for direct server-to-server communication.
29+
:::
30+
31+
## REST API v2 Authentication
32+
33+
Both API keys and OAuth tokens can be used to authenticate with the [REST API v2](/api-v2):
34+
35+
### Using API Keys
36+
37+
```text
38+
Authorization: Bearer sk_1234567890abcdef
39+
```
40+
41+
### Using OAuth Tokens
42+
43+
```text
44+
Authorization: Bearer atk_1234567890abcdef
45+
```
46+
47+
Both authentication methods use the same `Bearer` token format in the `Authorization` header, following [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235) standards.
48+
1549
## Finding API Keys
1650

1751
You can find the API keys for your project under **API keys** in the dashboard.

‎docs/projects/oauth-overview.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: OAuth 2.0 Authorization
3+
sidebar_label: OAuth Overview
4+
slug: oauth-overview
5+
excerpt: Secure, token-based access to RevenueCat's API using OAuth 2.0
6+
---
7+
8+
RevenueCat's OAuth 2.0 authorization server enables secure, token-based access to our API on behalf of developers. This allows third-party applications and tools to access RevenueCat data with explicit developer consent.
9+
10+
## Why Use OAuth?
11+
12+
OAuth tokens provide several advantages over traditional API keys:
13+
14+
- **Developer-level access** across all projects a user has access to
15+
- **Granular permission scopes** to limit access to only what's needed
16+
- **Enhanced security** with automatic token expiration
17+
- **Third-party integration support** for building ecosystem tools
18+
- **User consent** - developers explicitly authorize what data can be accessed
19+
20+
## Supported Flow
21+
22+
RevenueCat currently supports the **Authorization Code flow** with PKCE (Proof Key for Code Exchange) enforcement for public clients. This flow is secure for both server-side applications and native/mobile apps.
23+
24+
## Getting Started
25+
26+
To use OAuth with RevenueCat:
27+
28+
1. **Register your OAuth client** with our support team
29+
2. **Implement the authorization flow** in your application
30+
3. **Use access tokens** to make API requests on behalf of users
31+
32+
## Next Steps
33+
34+
- [Set up OAuth integration](/projects/oauth-setup) - Complete implementation guide
35+
- [View available scopes](/projects/oauth-setup#available-scopes) - See what permissions you can request
36+
- [Learn about token management](/projects/oauth-setup#token-management) - Handle access and refresh tokens

‎docs/projects/oauth-setup.mdx

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
---
2+
title: OAuth 2.0 Implementation Guide
3+
sidebar_label: OAuth Setup
4+
slug: oauth-setup
5+
excerpt: Complete guide to implementing OAuth 2.0 with RevenueCat's authorization server
6+
---
7+
8+
This guide walks you through implementing OAuth 2.0 authorization with RevenueCat's API.
9+
10+
## Client Registration
11+
12+
To integrate with RevenueCat's OAuth server, you'll need to register your application as an OAuth client. Contact our [support team](mailto:[email protected]) to register your client with the following information:
13+
14+
- **Client Name**: Display name for your application
15+
- **Client URI**: Your application's homepage URL
16+
- **Redirect URIs**: Valid callback URLs for your application
17+
- **Client Type**: Public (for native/desktop apps) or Confidential (for server-side apps)
18+
19+
## Authorization Flow
20+
21+
### Step 1: Initiate Authorization
22+
23+
Direct users to the authorization endpoint:
24+
25+
```
26+
GET https://api.revenuecat.com/oauth2/authorize
27+
```
28+
29+
**Required Parameters:**
30+
31+
- `client_id`: Your client identifier
32+
- `response_type`: Must be `code`
33+
- `redirect_uri`: Must match a registered redirect URI
34+
- `scope`: Space-separated list of requested permissions
35+
- `code_challenge`: PKCE code challenge (required for public clients)
36+
- `code_challenge_method`: Must be `S256` (required for public clients)
37+
38+
**Optional Parameters:**
39+
40+
- `state`: Random string to prevent CSRF attacks (recommended)
41+
42+
**Example Authorization URL:**
43+
44+
```url
45+
https://api.revenuecat.com/oauth2/authorize?
46+
client_id=your_client_id&
47+
response_type=code&
48+
redirect_uri=https://yourapp.com/callback&
49+
scope=project_configuration:apps:read&
50+
state=random_state_string&
51+
code_challenge=your_code_challenge&
52+
code_challenge_method=S256
53+
```
54+
55+
### Step 2: Handle Authorization Response
56+
57+
After the user grants permission, they'll be redirected to your `redirect_uri`.
58+
59+
**Success Response:**
60+
61+
```
62+
https://yourapp.com/callback?code=authorization_code&state=random_state_string
63+
```
64+
65+
**Error Response:**
66+
67+
```
68+
https://yourapp.com/callback?error=access_denied&error_description=description&state=random_state_string
69+
```
70+
71+
### Step 3: Exchange Code for Tokens
72+
73+
Exchange the authorization code for access and refresh tokens:
74+
75+
```bash
76+
curl -X POST https://api.revenuecat.com/oauth2/token \
77+
-H "Content-Type: application/x-www-form-urlencoded" \
78+
-d "grant_type=authorization_code&code=your_auth_code&redirect_uri=https://yourapp.com/callback&client_id=your_client_id&client_secret=your_client_secret"
79+
```
80+
81+
**Parameters:**
82+
83+
- `grant_type`: Must be `authorization_code`
84+
- `code`: The authorization code from Step 2
85+
- `redirect_uri`: Must match the redirect URI from Step 1
86+
- `client_id`: Your client identifier
87+
- `client_secret`: Your client secret (required for confidential clients)
88+
- `code_verifier`: PKCE code verifier (required for public clients)
89+
90+
**Success Response:**
91+
92+
```json
93+
{
94+
"access_token": "atk_...",
95+
"token_type": "Bearer",
96+
"expires_in": 3600,
97+
"refresh_token": "rtk_...",
98+
"scope": "project_configuration:apps:read"
99+
}
100+
```
101+
102+
## Token Management
103+
104+
### Access Tokens
105+
106+
- **Lifetime**: 1 hour
107+
- **Usage**: Include in API requests via `Authorization: Bearer {access_token}` header
108+
- **Prefix**: `atk_`
109+
110+
### Refresh Tokens
111+
112+
- **Lifetime**: 1 month
113+
- **Usage**: Exchange for new access tokens when they expire
114+
- **Prefix**: `rtk_`
115+
116+
### Refreshing Tokens
117+
118+
When your access token expires, use the refresh token to get a new pair:
119+
120+
```bash
121+
curl -X POST https://api.revenuecat.com/oauth2/token \
122+
-H "Content-Type: application/x-www-form-urlencoded" \
123+
-d "grant_type=refresh_token&refresh_token=your_refresh_token&client_id=your_client_id&client_secret=your_client_secret"
124+
```
125+
126+
**Parameters:**
127+
128+
- `grant_type`: Must be `refresh_token`
129+
- `refresh_token`: Your current refresh token
130+
- `client_id`: Your client identifier
131+
- `client_secret`: Your client secret (required for confidential clients)
132+
133+
:::warning Token Rotation
134+
When tokens are refreshed, both the old access and refresh tokens are revoked, and new ones are issued. Make sure to update your stored tokens.
135+
:::
136+
137+
## Available Scopes
138+
139+
Request only the scopes your application needs:
140+
141+
### Project Configuration
142+
143+
- `project_configuration:projects:read` - List projects
144+
- `project_configuration:apps:read` - Read app information
145+
- `project_configuration:apps:read_write` - Create, update, delete apps
146+
- `project_configuration:entitlements:read` - Read entitlements
147+
- `project_configuration:entitlements:read_write` - Manage entitlements
148+
- `project_configuration:offerings:read` - Read offerings
149+
- `project_configuration:offerings:read_write` - Manage offerings
150+
- `project_configuration:packages:read` - Read packages
151+
- `project_configuration:packages:read_write` - Manage packages
152+
- `project_configuration:products:read` - Read products
153+
- `project_configuration:products:read_write` - Manage products
154+
155+
## Making API Requests
156+
157+
Include the access token in the `Authorization` header:
158+
159+
```bash
160+
curl -H "Authorization: Bearer atk_your_access_token" \
161+
https://api.revenuecat.com/v2/projects
162+
```
163+
164+
## PKCE Implementation
165+
166+
For public clients, implement PKCE (Proof Key for Code Exchange) to enhance security:
167+
168+
### 1. Generate Code Verifier and Challenge
169+
170+
```javascript
171+
// Generate a random code verifier (43-128 characters)
172+
function generateCodeVerifier() {
173+
const array = new Uint8Array(32);
174+
crypto.getRandomValues(array);
175+
return base64URLEncode(array);
176+
}
177+
178+
// Create code challenge from verifier
179+
async function generateCodeChallenge(verifier) {
180+
const encoder = new TextEncoder();
181+
const data = encoder.encode(verifier);
182+
const digest = await crypto.subtle.digest("SHA-256", data);
183+
return base64URLEncode(new Uint8Array(digest));
184+
}
185+
186+
// Base64 URL encoding helper
187+
function base64URLEncode(str) {
188+
return btoa(String.fromCharCode.apply(null, str))
189+
.replace(/\+/g, "-")
190+
.replace(/\//g, "_")
191+
.replace(/=/g, "");
192+
}
193+
```
194+
195+
### 2. Use in Authorization Request
196+
197+
Include `code_challenge` and `code_challenge_method=S256` in your authorization URL.
198+
199+
### 3. Include in Token Exchange
200+
201+
Send the original `code_verifier` when exchanging the authorization code for tokens.
202+
203+
## Error Handling
204+
205+
### Authorization Errors
206+
207+
- `invalid_request` - Missing or invalid parameters
208+
- `unauthorized_client` - Client not authorized for this grant type
209+
- `access_denied` - User denied authorization
210+
- `unsupported_response_type` - Invalid response type
211+
- `invalid_scope` - Requested scope is invalid or unknown
212+
- `server_error` - Internal server error
213+
214+
### Token Errors
215+
216+
- `invalid_request` - Missing or invalid parameters
217+
- `invalid_client` - Client authentication failed
218+
- `invalid_grant` - Authorization code/refresh token is invalid or expired
219+
- `unauthorized_client` - Client not authorized for this grant type
220+
- `unsupported_grant_type` - Grant type not supported
221+
222+
## Best Practices
223+
224+
1. **Store tokens securely** - Never expose tokens in client-side code
225+
2. **Implement proper error handling** - Handle token expiration gracefully
226+
3. **Use HTTPS only** - All OAuth flows must use secure connections
227+
4. **Validate state parameter** - Prevent CSRF attacks
228+
5. **Request minimal scopes** - Only request permissions you actually need
229+
6. **Implement token refresh** - Handle access token expiration automatically
230+
231+
## Rate Limits
232+
233+
OAuth tokens are subject to the same rate limits as API keys. Monitor your usage and implement appropriate backoff strategies.
234+
235+
## Support
236+
237+
For questions about OAuth integration or to register your client, contact our support team at [[email protected]](mailto:[email protected]).

‎docs/tools/mcp/setup.mdx

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -42,21 +42,17 @@ Configure the inspector with:
4242

4343
### Using with VS Code Copilot
4444

45-
Add to your VS Code settings:
45+
Add to your Visual Studio Code `mcp.json`:
4646

4747
```json
4848
{
49-
"mcp": {
50-
"servers": {
51-
"revenuecat": {
52-
"type": "http",
53-
"url": "https://mcp.revenuecat.ai/mcp",
54-
"headers": {
55-
"Authorization": "Bearer YOUR_API_V2_SECRET_KEY"
56-
}
57-
}
58-
}
59-
}
49+
"servers": {
50+
"revenuecat-mcp": {
51+
"url": "https://mcp.revenuecat.ai/mcp",
52+
"type": "http"
53+
}
54+
},
55+
"inputs": []
6056
}
6157
```
6258

@@ -83,6 +79,16 @@ Add to your Claude Desktop configuration:
8379
}
8480
```
8581

82+
### OAuth Authentication Support
83+
84+
RevenueCat MCP Server also supports OAuth authentication for supported clients. Currently supported:
85+
86+
- **Visual Studio Code** - Automatic OAuth flow for seamless authentication
87+
88+
> **🔧 Third-Party Integration**:
89+
>
90+
If you'd like to integrate your services with RevenueCat MCP Server, please contact us at [RevenueCat Support](mailto:[email protected]) so we can set up OAuth clients for your application.
91+
8692
## Local MCP Extension Setup
8793

8894
### 1. Install Extension

‎sidebars.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,11 @@ const projectsCategory = Category({
5858
Page({ slug: "amazon-server-notifications" }),
5959
],
6060
}),
61+
SubCategory({
62+
label: "OAuth",
63+
slug: "projects/oauth-overview",
64+
items: [Page({ slug: "projects/oauth-setup" })],
65+
}),
6166
SubCategory({
6267
label: "Project Settings",
6368
items: [

0 commit comments

Comments
 (0)