Authentication

Seekora uses header-based authentication. Every API request must include your Store ID and the appropriate secret key. There are no OAuth flows or token exchanges — simply pass your credentials as HTTP headers.

Credentials Overview

Each store has three credentials:

Credential	Description
Store ID	Unique identifier for your store. Included in every request.
Read Secret	Used for search, autocomplete, filters, and other read operations. Safe to use in client-side code.
Write Secret	Used for indexing documents, updating schemas, and modifying store configuration. Must be kept server-side only.

You can find all three values in the Seekora Dashboard under Store Settings > API Keys.

Request Headers

Header	Required	Description
x-storeid	Yes	Your Store ID.
x-storesecret	Yes (read operations)	Read secret key. Used for search, suggestions, and filter endpoints.
x-store-write-secret	Yes (write operations)	Write secret key. Used for indexing, schema, and configuration endpoints.
x-user-id	No	Logged-in user identifier. Enables personalized search results and analytics.
x-anon-id	No	Anonymous visitor identifier. Used for personalization before a user logs in.
x-session-id	No	Current browsing session identifier. Used for session-level analytics.

Base URL

All API requests are made against the following base URL:

https://api.seekora.ai

Example: Read Request

A typical search request using the read secret:

curl -X POST https://api.seekora.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -d '{
    "q": "running shoes"
  }'

Example: Write Request

A schema update using the write secret:

curl -X POST https://api.seekora.ai/api/v1/stores/your-store-id/schema \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-store-write-secret: your-write-secret" \
  -d '{
    "fields": [
      { "name": "title", "type": "string", "facet": false },
      { "name": "price", "type": "float", "facet": true }
    ]
  }'

Security Best Practices

• Never expose the write secret in client-side code. The write secret grants full access to modify your store data. Use it only in server-side applications or CI/CD pipelines.
• Use the read secret in browsers and mobile apps. The read secret is scoped to search and read operations and is safe to include in frontend code.
• Rotate secrets if compromised. You can regenerate secrets from the Seekora Dashboard without downtime. Update your applications with the new values immediately after rotation.
• Use environment variables. Store your credentials in environment variables rather than hardcoding them in source files.