Endpoint
/v1/feedbackSubmit one feedback item per request. The project and Test/Live mode come from the API key. This endpoint does not expose feedback reads.
Authentication
Send a project key in the Authorization header. Test keys begin with fp_test_; Live keys begin with fp_live_. Keep keys on your server. Credentials in query parameters are rejected.
Hosted feedback widget
Add the hosted, dependency-free widget to a page. Replace the sample script host with the deployment's BETTER_AUTH_URL public application origin; the widget loads its stylesheet and submits feedback through that same origin. It renders in Shadow DOM, while your server supplies short-lived tokens so your long-lived API key never reaches browser code.
<script
src="https://feedback.example.com/widget/v1.js"
data-token-url="/api/feedback-token"
data-label="Feedback"
data-primary-color="#626de8"
data-context='{"product":"billing","plan":"pro"}'
defer
></script>Set FEEDBACK_PORTAL_URL in your server environment to the Feedback Portal public application origin (the deployment value of BETTER_AUTH_URL). Keep FEEDBACK_PORTAL_API_KEY server-side. Your same-origin /api/feedback-token endpoint MUST rate-limit its public requests, derive the page origin and authenticated customer-user claims itself, call POST /v1/widget/tokens, and forward the response with Cache-Control: no-store.
async function createFeedbackToken(request: Request): Promise<Response> {
const pageOrigin = request.headers.get("origin");
if (pageOrigin === null) {
return new Response("Origin is required", { status: 403 });
}
const customerUser = await getAuthenticatedCustomerUser(request);
const tokenResponse = await fetch(
process.env.FEEDBACK_PORTAL_URL + "/v1/widget/tokens",
{
method: "POST",
headers: {
Authorization: "Bearer " + process.env.FEEDBACK_PORTAL_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
origin: pageOrigin,
user: customerUser ? {
id: customerUser.id,
name: customerUser.name,
email: customerUser.email,
} : undefined,
}),
cache: "no-store",
}
);
const headers = new Headers({
"Cache-Control": "no-store",
"Content-Type": tokenResponse.headers.get("content-type") || "application/json",
});
return new Response(tokenResponse.body, {
status: tokenResponse.status,
headers,
});
}The API key must be a Test or Live key stored in a server-side secret store. The token endpoint accepts an exact page origin and optional string id, name, and email claims. The email is validated. Anonymous visitors are supported; customer-user claims remain distinct from the visitor-entered name and email fields.
Configure exact origins in the project settings. Live use requires HTTPS; Test may use loopback HTTP origins such as http://localhost:3000. Token grants last 15 minutes and allow one feedback item. Keep the widget token in memory only. For an uncertain retry, reuse the same payload and Idempotency-Key; if the token expires, request a fresh token and keep the same key. Widget errors use RFC 9457 Problem Details: 401 credentials, 403 origin,409 idempotency conflict, 422 invalid input,429 rate limit with Retry-After, and 500unexpected failure.
The optional data-label and six-digit hexadecimal data-primary-color attributes configure the launcher. The default primary colour is #626de8. data-context accepts a JSON object of flat string, number, and Boolean values. Custom, automatic, and customer-user context share the 20-key, 8 KB limit. Automatic page and browser context is on by default; data-collect-context="false" disables only that automatic collection. The public API exposes FeedbackPortalWidget.open() only.
A strict Content Security Policy needs the Feedback Portal origin in script-src, connect-src, and style-src;connect-src must also allow the customer's same-origin token proxy. No unsafe-inline directive is required. The widget does not send referrer, query-string, or fragment data.
Request fields
| Field | Required | Rules |
|---|---|---|
type | Yes | idea, issue, or general |
message | Yes | 1–10,000 characters |
title | No | Up to 200 characters |
submitter.name/email | No | Each may be omitted independently |
context | No | Flat string/number/Boolean map; 20 keys and 8 KB maximum |
bugDetails | No | Issue-only object; optional reproduction steps, expected/actual result, environment, and version. Text limits: 10,000 characters per steps/result field and 200 per environment/version field. |
The API uses issue for bug reports; the portal displays those items as Bugs.
Do not submit passwords, payment credentials, or highly sensitive personal data.
cURL
curl https://feedback.example.com/v1/feedback \
--request POST \
--header 'Authorization: Bearer fp_live_YOUR_PROJECT_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: order-123-feedback-1' \
--data '{
"type": "issue",
"title": "Profile save returns an error",
"message": "The application displays an error after saving a profile.",
"submitter": { "name": "Example User", "email": "[email protected]" },
"bugDetails": {
"stepsToReproduce": "Open Settings, change the display name, and select Save.",
"expectedResult": "The new display name appears in the profile.",
"actualResult": "An error appears after saving, although the new name is shown.",
"environment": "Chrome 126 on macOS",
"version": "2.4.1"
},
"context": { "platform": "web" }
}'TypeScript
Generate an idempotency key once per submission. The example keeps it unchanged for up to three attempts, including network failures, server errors, and rate limits.
const idempotencyKey = crypto.randomUUID();
const maximumAttempts = 3;
const requestBody = JSON.stringify({
type: "idea",
message: "The export takes a long time.",
title: "Slow export",
context: { version: "2.4", platform: "web" },
});
async function submitFeedback(): Promise<void> {
for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
let response: Response;
try {
response = await fetch("https://feedback.example.com/v1/feedback", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.FEEDBACK_PORTAL_KEY,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: requestBody,
});
} catch (error) {
if (attempt === maximumAttempts) throw error;
await new Promise((resolve) => setTimeout(resolve, attempt * 1000));
continue;
}
const isRetryable = response.status === 429 || response.status >= 500;
const shouldRetry = isRetryable && attempt < maximumAttempts;
if (shouldRetry) {
const retryAfterSeconds = response.status === 429 ? Number(response.headers.get("Retry-After") ?? "60") : attempt;
await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000));
continue;
}
if (!response.ok) {
const problem = await response.json();
throw new Error("Feedback API " + problem.status + ": " + problem.detail);
}
const created = await response.json();
console.info("Feedback saved", created.id, created.status);
return;
}
throw new Error("Feedback retry attempts were exhausted.");
}Responses and retries
| Status | Meaning |
|---|---|
201 | Persisted; response includes the feedback ID, creation time, type, and New status. |
400 | Malformed JSON or query parameters supplied. |
401 | Invalid, expired, or revoked key. These cases use the same response. |
404 | Project could not be found. |
409 | Idempotency key was reused with different content. |
422 | Request validation failed. |
429 | Per-key rate limit reached. Wait for Retry-After, then retry with the same key and payload. |
500 | Unexpected storage or server failure. Retry with the same idempotency key. |
Errors use RFC 9457 Problem Details with type, title, status, detail, and instance. Idempotency keys are retained for 24 hours. Reusing a key with the same payload returns the original creation result; different content returns 409.
Rate limits are per API key and configurable by the operator. The local example starts at 60 requests per minute; production values MUST be set after deployment capacity is selected and validated.
OpenAPI 3.1 specificationRecommended setup
- Create a project and a Test key.
- Send a test submission from your server.
- Verify it in the portal’s Test view.
- Create a Live key and configure it only in your production server environment.