Skip to content

Commit dab3112

Browse files
smeubanksmeubank
authored
feat(partners)add-enablement-docs (#14095)
Draft of converting 2 internal docs into public facing partnership enablement pages - account provisioning - oauth New section under "product walkthroughs" which "walkthrough" is maybe a stretch, but this is a start and we can put it where we agree makes the most sense, and be discoverable. [preview](https://sentry-docs-git-featpartnersadd-enablement-docs.sentry.dev/product/partnership-platform) <img width="455" alt="image" src="https://github.com/user-attachments/assets/80612cc8-604e-4f94-94f3-d203b9563e70" />
1 parent 9ed99b8 commit dab3112

File tree

3 files changed

+591
-0
lines changed

3 files changed

+591
-0
lines changed

‎docs/product/partnership-platform/account-provisioning-api.mdx

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
Sentry platform---
2+
title: "Account Provisioning API"
3+
description: "Learn how to automatically provision Sentry organizations for your customers using our provisioning API."
4+
sidebar_order: 1
5+
---
6+
7+
# Account Provisioning API
8+
9+
The Sentry Provisioning API allows partner platforms to automatically create Sentry organizations for their customers. This enables seamless onboarding of your users to Sentry's error monitoring and performance insights.
10+
11+
## Overview
12+
13+
When you call the Sentry provisioning API on behalf of your customer for the first time, the customer receives:
14+
15+
- **A Sentry Organization** with the same name as their organization on your platform
16+
- **A Default Team** for collaboration within the organization
17+
- **Organization Ownership** assigned to the provided email address
18+
- **Subscription Plan** based on your partnership agreement
19+
- **Pre-configured Projects** (optional) that you specify
20+
- **Integration Token** (optional) for managing the organization programmatically
21+
22+
## API Endpoint
23+
24+
```
25+
POST https://sentry.io/remote/channel-provision/account/
26+
```
27+
28+
## Authentication
29+
30+
The API requires a custom `X-Request-Signature` header with a SHA256 HMAC signature. The signature is built using your `API_SECRET_KEY` and the request body.
31+
32+
### Signature Generation
33+
34+
```python
35+
import hmac
36+
import hashlib
37+
import json
38+
39+
def generate_signature(data, secret_key):
40+
secret_key_bytes = secret_key.encode("utf-8")
41+
json_data = json.dumps(data)
42+
data_bytes = json_data.encode("utf-8")
43+
signature = hmac.new(
44+
key=secret_key_bytes,
45+
msg=data_bytes,
46+
digestmod=hashlib.sha256
47+
).hexdigest()
48+
return signature
49+
```
50+
51+
## Request Parameters
52+
53+
| Parameter | Type | Required | Description |
54+
|-----------|------|----------|-------------|
55+
| `channel` | string | Yes | Your partner name (case insensitive) |
56+
| `email` | string | Yes | Customer's email address (becomes org owner) |
57+
| `organizationName` | string | Yes | Customer's organization name (max 50 chars) |
58+
| `organizationID` | string | Yes | Unique ID for customer's organization on your platform |
59+
| `hasAgreedTerms` | boolean | Yes | Customer's agreement to Sentry terms |
60+
| `timestamp` | integer | Yes | Current timestamp for request expiration |
61+
| `url` | string | Yes | Must be `https://sentry.io/remote/channel-provision/account/` |
62+
| `projects` | array | No | List of projects to create |
63+
| `region` | string | No | Data residency (`us` or `de`, default: `us`) |
64+
| `isTest` | boolean | No | Set to `true` for testing (default: `false`) |
65+
66+
### Project Object Structure
67+
68+
```json
69+
{
70+
"name": "project-name",
71+
"platform": "java"
72+
}
73+
```
74+
75+
### Supported Platforms
76+
77+
The `platform` field supports all [Sentry platform identifiers](/platforms/), including:
78+
- `javascript`, `python`, `java`, `csharp`, `php`, `ruby`, `go`, `rust`, `swift`, `kotlin`, `dart`, and more
79+
80+
## Example Request
81+
82+
```python
83+
import requests
84+
import json
85+
import time
86+
87+
URL = "https://sentry.io/remote/channel-provision/account/"
88+
API_SECRET_KEY = "your-partner-specific-secret-key"
89+
90+
DATA = {
91+
"channel": "Your Platform Name",
92+
"organizationName": "Customer Corp",
93+
"organizationID": "unique-customer-id",
94+
"email": "[email protected]",
95+
"projects": [
96+
{"name": "web-app", "platform": "javascript"},
97+
{"name": "api-service", "platform": "python"}
98+
],
99+
"hasAgreedTerms": True,
100+
"timestamp": int(time.time()),
101+
"url": URL,
102+
"isTest": False
103+
}
104+
105+
# Generate signature
106+
signature = generate_signature(DATA, API_SECRET_KEY)
107+
108+
# Make request
109+
response = requests.post(
110+
URL,
111+
data=json.dumps(DATA),
112+
headers={"X-Request-Signature": signature}
113+
)
114+
115+
print(response.json())
116+
```
117+
118+
## Response
119+
120+
### Success (200)
121+
122+
```json
123+
{
124+
"email": "[email protected]",
125+
"organization": {
126+
"id": "123",
127+
"slug": "customer-corp",
128+
"name": "Customer Corp"
129+
},
130+
"projects": [
131+
{
132+
"dsn": "https://[email protected]/123",
133+
"project": {
134+
"id": "456",
135+
"slug": "web-app",
136+
"name": "web-app",
137+
"platform": "javascript"
138+
}
139+
}
140+
],
141+
"integration_api_token": "your-integration-token"
142+
}
143+
```
144+
145+
### Error Responses
146+
147+
- **400 Bad Request**: Invalid parameters (check response body for details)
148+
- **401 Unauthorized**: Invalid signature (check your API_SECRET_KEY)
149+
- **500 Server Error**: Internal server error (check response body for details)
150+
151+
## Additional Operations
152+
153+
### Adding Projects
154+
155+
Call the API again with new projects to add them to an existing organization:
156+
157+
```python
158+
DATA = {
159+
# ... existing parameters ...
160+
"projects": [
161+
{"name": "new-service", "platform": "go"}
162+
]
163+
}
164+
```
165+
166+
### Adding Managers
167+
168+
Add additional users as managers to the organization:
169+
170+
```python
171+
DATA = {
172+
# ... existing parameters ...
173+
"email": "[email protected]" # New manager email
174+
}
175+
```
176+
177+
## Customer Experience
178+
179+
### Welcome Email
180+
181+
When you provision an organization, the customer receives:
182+
- A welcome email with organization details
183+
- Instructions for managing their Sentry organization
184+
- Information about your partnership integration
185+
- Support contact information
186+
187+
### Partner-Specific Features
188+
189+
Based on your partnership agreement, you can enable:
190+
191+
- **Partner Presence**: Show your platform as an organization member
192+
- **Persistent Plan**: Allow customers to upgrade plans independently
193+
- **Quota Visibility**: Control visibility of usage quotas
194+
195+
## Integration Token
196+
197+
The response includes an `integration_api_token` that allows you to:
198+
- Create and manage projects
199+
- Manage organization members
200+
- Access Sentry APIs on behalf of the customer
201+
202+
Token permissions are defined in your partnership agreement.
203+
204+
## Best Practices
205+
206+
1. **Store organization mappings**: Keep track of the relationship between your customer IDs and Sentry organization IDs
207+
2. **Handle errors gracefully**: Implement proper error handling for failed provisioning
208+
3. **Use test mode**: Set `isTest: true` during development and testing
209+
4. **Respect rate limits**: Implement appropriate delays between requests
210+
5. **Secure your secret key**: Store your API_SECRET_KEY securely and never expose it in client-side code
211+
212+
## Support
213+
214+
For questions about the provisioning API or partnership integration, contact:
215+
**Email:** [email protected]

‎docs/product/partnership-platform/index.mdx

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: "Partnership Platform"
3+
description: "Learn how to integrate Sentry into your platform and provide error monitoring and performance insights to your customers."
4+
sidebar_order: 35
5+
---
6+
7+
# Partnership Platform
8+
9+
Sentry offers powerful partnership capabilities that allow you to integrate error monitoring and performance insights directly into your platform. Whether you're a developer platform, hosting provider, or SaaS application, you can leverage Sentry's monitoring capabilities to enhance your customer experience.
10+
11+
## What's Available
12+
13+
Sentry provides two main integration paths for partners:
14+
15+
### 1. [Account Provisioning API](/product/partnership-platform/account-provisioning-api/)
16+
17+
Automatically create Sentry organizations for your customers with our provisioning API. This allows you to:
18+
19+
- **Seamlessly onboard customers** to Sentry monitoring
20+
- **Create pre-configured organizations** with projects and teams
21+
- **Manage customer access** through integration tokens
22+
- **Support multiple regions** (US and EU data residency)
23+
24+
### 2. [OAuth Integration](/product/partnership-platform/oauth-integration/)
25+
26+
Enable existing Sentry customers to connect their accounts to your platform through OAuth:
27+
28+
- **Account linking** between your platform and Sentry organizations
29+
- **Permission-based access** with configurable scopes
30+
- **User-controlled permissions** with easy revocation
31+
- **Seamless authentication flow** for your users
32+
33+
## Benefits for Your Platform
34+
35+
Integrating with Sentry's partnership platform provides several advantages:
36+
37+
- **Enhanced developer experience** with built-in error monitoring
38+
- **Reduced support burden** by helping customers debug issues faster
39+
- **Competitive differentiation** with enterprise-grade monitoring
40+
- **Revenue opportunities** through monitoring capabilities
41+
- **Improved customer retention** with better application reliability
42+
43+
## Getting Started
44+
45+
If you're interested in integrating Sentry into your platform, our partnership team can help you get started. We'll work with you to:
46+
47+
- Determine the best integration approach for your use case
48+
- Set up the necessary API credentials and configurations
49+
- Provide technical guidance and implementation support
50+
- Establish the partnership agreement and terms
51+
52+
## Contact Us
53+
54+
Ready to explore partnership opportunities with Sentry? Reach out to our partnership platform team:
55+
56+
**Email:** [email protected]
57+
58+
Our team will guide you through the integration process and help you leverage Sentry's monitoring capabilities to enhance your platform.

0 commit comments

Comments
 (0)