← SearchX

API Reference

API Authentication

Learn how to authenticate with the SearchX API using Bearer tokens and app-scoped API keys.

Overview

The SearchX API uses Bearer token authentication with app-scoped API keys. Each API key is bound to a specific application and can only access that application's data.

Base URL: https://admin.searchxengine.ai/api/v2

Interactive API Documentation

Try the API live with our Swagger UI: Open Interactive API Docs →

Getting Your Credentials

  1. Log in to the SearchX Dashboard
  2. Navigate to Applications and select your application
  3. Go to the Keys tab
  4. Copy your Application ID (10-character alphanumeric)
  5. Copy your API Key (starts with key_)

Each application has one API key. You use the same key for server-side REST API calls and for the storefront widget.

Handle Your API Key Like a Credential

Keep your API key out of source control. For server-side calls (REST API, MCP clients, scripts), store it in environment variables. The same key is used by the storefront widget, where it can only run searches, so placing it in your storefront page is expected and safe.

Authentication Methods

The SearchX API supports three authentication methods. You can authenticate using:

  1. Bearer Token (Recommended): Pass API key in Authorization header
  2. Query Parameter: Pass API key as api_key query parameter
  3. Request Body: Pass API key in request body (POST/PUT only)
GET /api/v2/applications/YOUR_APP_ID HTTP/1.1
Host: admin.searchxengine.ai
Authorization: Bearer YOUR_API_KEY

cURL Example:

curl -X GET "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Header Format:

Authorization: Bearer YOUR_API_KEY

Important:

  • Include the word Bearer followed by a space
  • Then your API key
  • Header name is Authorization (note the 'z' in American spelling)

Method 2: Query Parameter

Alternatively, pass the API key as a query parameter:

GET /api/v2/applications/YOUR_APP_ID?api_key=YOUR_API_KEY HTTP/1.1
Host: admin.searchxengine.ai

cURL Example:

curl -X GET "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID?api_key=YOUR_API_KEY"

When to Use Query Parameters

Query parameter authentication is useful for:

  • Quick testing in a browser
  • Tools that don't support custom headers
  • Webhooks or callbacks with limited configuration

For production applications, use the Bearer token method for better security practices.

Method 3: Request Body

For POST and PUT requests, you can include the API key in the request body:

POST /api/v2/applications/YOUR_APP_ID/search HTTP/1.1
Host: admin.searchxengine.ai
Content-Type: application/json

{
  "api_key": "YOUR_API_KEY",
  "q": "shoes",
  "limit": 20
}

cURL Example:

curl -X POST "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "q": "shoes",
    "limit": 20
  }'

Update Application Example:

PUT /api/v2/applications/YOUR_APP_ID HTTP/1.1
Host: admin.searchxengine.ai
Content-Type: application/json

{
  "api_key": "YOUR_API_KEY",
  "name": "Updated Store Name",
  "feed_url": "https://mystore.com/products.xml"
}

Body Authentication Scope

Request body authentication only works for POST and PUT endpoints. GET requests must use either Bearer token or query parameter authentication.

App-Scoped Security

The API enforces app-scoped authentication for enhanced security:

✅ Allowed:  /api/v2/applications/a1b2c3d4e5/search
            with API key for a1b2c3d4e5

❌ Forbidden: /api/v2/applications/a1b2c3d4e5/search
             with API key for x9y8z7w6v5
             → 403 Forbidden

How It Works

  1. API Key Creation: Each API key is bound to a specific application
  2. Request Validation: Middleware validates {app_id} in URL matches the API key
  3. Cross-App Protection: Cannot access other applications, even in same organization

Enhanced Security

This app-scoped model prevents accidental data leaks between applications and provides better audit trails. Each application's data is isolated even within the same organization.

Using API Keys

Server-Side (REST API)

Use the Authorization header for all requests:

const response = await fetch(
  'https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID/search',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SEARCHX_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ q: 'shoes', limit: 20 }),
  },
);

Client-Side (SDK)

For client-side integration, use the SDK via CDN with the same API key:

<!-- Add to your HTML -->
<script src="https://sdk.searchxengine.ai/searchx-sdk.umd.js"></script>

<script>
  window.addEventListener('load', function () {
    if (window.SearchXSDK) {
      SearchXSDK.init({
        app_id: 'YOUR_APP_ID',
        api_key: 'YOUR_API_KEY',
        // ...
      });
    }
  });
</script>

See HTML Integration for complete setup guide.

Your API Key in the Browser

Your API key is visible in the page source of your storefront, and that is expected. When used from the browser, the key can only run searches. It cannot change application settings, import products or read analytics. For server-side calls, keep the key in environment variables and out of source control.

Common Authentication Errors

401 Unauthorized

Error: Missing or invalid API key

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": 4011,
  "message": "Missing API Key or Bearer Token."
}

Solutions:

  • Check Authorization header is present
  • Verify Bearer prefix is included
  • Confirm API key is correct

403 Forbidden

Error: API key doesn't belong to application

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": 4031,
  "message": "API key does not belong to this application."
}

Solutions:

  • Verify {app_id} in URL matches your API key
  • Check you're using the correct API key for this application
  • Confirm app_id is correct (check dashboard)

404 Not Found

Error: The requested resource was not found (for example, an unknown app_id)

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "errorCode": 4041,
  "message": "Resource not found."
}

Solutions:

  • Verify application ID is correct
  • Check application exists in dashboard
  • Ensure using production vs staging environment

See API Errors for complete error reference.

Previous
Playground
Next
Applications API