Developer guide

Send feedback through the API.

A small server-to-server integration is all it takes. Use the guide below to submit product feedback and structured bug reports safely and reliably.

Explore the product

Endpoint

POST/v1/feedback

Submit 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.

Never put an API key in browser code, a mobile app bundle, a URL, or a public repository.

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

FieldRequiredRules
typeYesidea, issue, or general
messageYes1–10,000 characters
titleNoUp to 200 characters
submitter.name/emailNoEach may be omitted independently
contextNoFlat string/number/Boolean map; 20 keys and 8 KB maximum
bugDetailsNoIssue-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

StatusMeaning
201Persisted; response includes the feedback ID, creation time, type, and New status.
400Malformed JSON or query parameters supplied.
401Invalid, expired, or revoked key. These cases use the same response.
404Project could not be found.
409Idempotency key was reused with different content.
422Request validation failed.
429Per-key rate limit reached. Wait for Retry-After, then retry with the same key and payload.
500Unexpected 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 specification

Recommended setup

  1. Create a project and a Test key.
  2. Send a test submission from your server.
  3. Verify it in the portal’s Test view.
  4. Create a Live key and configure it only in your production server environment.
Get started with Feedback Portal