Authentication

Overview

The Reponse API uses Bearer authentication. Every request must include your workspace API key in the `Authorization` header. Keys are scoped to a single workspace and grant access to all resources within that workspace.

Prerequisites

• A Reponse account with at least one workspace
• An API key generated from the dashboard

Step 1 — Generate an API Key

Navigate to **Settings → API Keys** in your workspace dashboard. Click **Create key**, give it a label (e.g. `production-backend`), and copy the value immediately — it will not be shown again.

Step 2 — Include the Key in Requests

Pass the key as a Bearer token in the `Authorization` header:

Authorization: Bearer <your_api_key>

cURL Example

curl -X GET https://api.reponse.ai/v1/catalog/products \
  -H "Authorization: Bearer rp_live_abc123..."

TypeScript Example

const response = await fetch("https://api.reponse.ai/v1/catalog/products", {
  headers: {
    Authorization: `Bearer ${process.env.REPONSE_API_KEY}`,
  },
});

Key Types

Test keys return realistic responses but never mutate production data. Use them during development and in CI pipelines.

Rate-Limit Headers

Every response includes rate-limit metadata so your application can self-throttle:

Key Rotation

You can have up to five active keys per workspace. To rotate a key:

1. Create a new key in the dashboard.
2. Deploy the new key to your servers.
3. Revoke the old key once all traffic uses the new one.

Revoked keys return `401 Unauthorized` immediately.

Security Best Practices

• Never expose live keys in client-side code. Use them only from a server or proxy requests through your backend.
• Store keys in environment variables (REPONSE_API_KEY), not in source control.
• Use test keys (rp_test_) for local development and CI.
• Rotate keys periodically and after any team-member departure.

Storefront Public Auth

Storefront applications (e.g. the Next.js starter) can access **read-only catalog endpoints** and **shopping operations** (carts, checkout, shipping) without an API key by passing a `x-workspace-id` header instead.

This keeps the onboarding frictionless: merchants only need their Workspace ID to launch a storefront. Sensitive admin endpoints (orders management, inventory writes, CRM) still require a full API key.

How it Works

Pass your Workspace ID in the `x-workspace-id` header:

curl -X GET https://api.reponse.ai/v1/products \
  -H "x-workspace-id: your-workspace-uuid"

Or as a query parameter:

GET https://api.reponse.ai/v1/products?workspace_id=your-workspace-uuid

Public Endpoints

The following endpoints accept `x-workspace-id` authentication:

All other endpoints require a Bearer API key.

Rate Limits

Public-auth requests are rate-limited per IP address:

Requests authenticated with a Bearer API key are not rate-limited.

SDK Usage

The `@reponseai/sdk` supports both authentication modes:

import { Reponse, client } from "@reponseai/sdk";

// Option A: API key auth (admin/backend)
const reponse = new Reponse({ apiKey: process.env.REPONSE_API_KEY! });

// Option B: Public auth (storefront)
client.setConfig({
  baseUrl: "https://reponse.ai/api",
  headers: { "x-workspace-id": process.env.NEXT_PUBLIC_WORKSPACE_ID! },
});

Troubleshooting