Zum Inhalt springen

Getting started

Authentication & security

https://searcio.com/api/v1

Die Dokumentation ist auf Englisch verfasst.

Auf dieser Seite

Searcio uses two credential types with deliberately different security properties: one for writing (trusted, used on your server) and one for searching (public, used in the browser).

flowchart TD
    subgraph Server["Your server / plugin backend"]
        WK["Write key + Write secret"]
    end
    subgraph Browser["Your storefront (untrusted)"]
        SK["Search key (public)"]
    end
    WK -->|"ingest: POST/PUT/DELETE"| API["/api/v1/sites/{id}/documents"]
    SK -->|"read: GET search"| API2["/api/v1/sites/{id}/search"]
    API2 -. "own domain only + CORS" .-> Browser

Write credentials (ingest)

Used for indexing, from server to server. Never expose these in a browser.

  • Write key (wk_…) identifies the site. Send it in the X-Write-Key header.
  • Write secret is the password half. Send it in the X-Write-Secret header.
http
POST /api/v1/sites/123/documents HTTP/1.1
Host: search.example.com
X-Write-Key: wk_live_abc123
X-Write-Secret: s3cr3t-shown-once
Content-Type: application/json

Security properties:

  • The secret is stored hashed (bcrypt), so Searcio cannot reveal it again. It is shown once, when the site is created or its keys are rotated.
  • The key is compared in constant time (hash_equals) and the secret with a hash verification, which protects against timing attacks.
  • A disabled site rejects all ingest with 403.
  • Invalid or missing credentials return 401.

Rotating credentials

If a secret leaks, use Rotate keys on the site's page in the Searcio dashboard. This issues a new write key, write secret and search key, and invalidates the old ones. Update your plugin configuration straight away.

Search credentials (query)

Used for public search from the browser. The key is safe to ship to the client because you can restrict it to your own domains.

  • Search key (sk_…), sent either as a key query parameter or in an X-Search-Key header.
bash
# Query parameter (simplest for the browser, no preflight)
GET /api/v1/sites/123/search?q=shoes&key=sk_live_xyz

# Or header
GET /api/v1/sites/123/search?q=shoes
X-Search-Key: sk_live_xyz

The key works on its own site

A search key in a web page is visible to anyone, and that is expected. It works only on the website it was created for:

  • The host in a search request's Origin header must be the site's domain, with or without www.. A request from any other website, another subdomain such as en.shop.acme.com included, is rejected with 403 domain_not_allowed.
  • CORS headers (Access-Control-Allow-Origin) are returned only for those origins, so browsers on other websites cannot read your results.
  • A site connected through a plugin (WordPress, WooCommerce, Magento) also refuses requests that name no website, since a plugin always searches from the visitor's browser.
  • A site with a REST integration may search from its own server, without an Origin header.
  • A shop that runs on more than one domain or subdomain, such as a separate domain per language, keeps working: ask support to add the other domains.

There is nothing to configure or to switch on: the domain is the one the site was connected with, and the rule holds for every site from its first request.

flowchart TD
    R["Search request<br/>Origin: shop.acme.com"] --> K{"Search key valid?"}
    K -- No --> E401["401"]
    K -- Yes --> M{"The site's domain, with or without www?"}
    M -- No --> E403["403 domain_not_allowed"]
    M -- Yes --> OK["Serve + CORS headers"]

Preflights

Any browser request that is not a simple request, such as one sending Content-Type: application/json (which includes POST /assistant), is preceded by an OPTIONS preflight. Preflights are answered with the same decision as the request itself:

Header Value
Access-Control-Allow-Origin The request's origin, when the key works there. Absent otherwise.
Access-Control-Allow-Methods The methods the endpoint actually accepts.
Access-Control-Allow-Headers Echoes the requested headers.
Access-Control-Max-Age 600, the number of seconds the browser may cache the result.
Vary Origin, always.

Two things are worth knowing when you build against this:

  • Put the search key in ?key=, not in X-Search-Key. A browser sends no custom headers with a preflight, so a preflight for a request that carries the key only in the header has no credential to identify the site with, and cannot be allowed.
  • A preflight that is not allowed still returns 204, only without Access-Control-Allow-Origin, which is what makes the browser block the real request. The response is identical whether or not the site id in the path exists, so preflights cannot be used to discover which sites exist.

The connect endpoint

POST /connect (see Building a plugin) is the one endpoint that takes no key at all. That is intentional: it is the endpoint that issues your write and search keys in the first place. Instead of a credential, it is protected by other means:

  • Rate limiting: 20 requests per hour per IP address, 5 per day per domain, and 5 per day per recipient email address, so the sign-in email it sends cannot be used to flood an inbox or reserve someone else's address. These limits are far tighter than the general limit of 300 requests per minute.
  • One connection per domain: a site_url can be connected automatically only once. A repeat attempt with a different idempotency_key is rejected with 409, which is what stops anyone from claiming a domain they do not control.
  • Email ownership is never assumed. If admin_email belongs to an existing Searcio user, nothing is created or disclosed until that person clicks a signed link emailed to that address. An anonymous request that names someone's email address is never enough on its own.
  • Domain verification runs afterwards, in the background, as an additional signal. It never blocks or restricts the keys already issued; see Building a plugin for the exact contract.

Security controls at a glance

Control Ingest Search
Transport HTTPS only HTTPS only
Identity Write key (constant-time compare) Search key (constant-time compare)
Proof Hashed write secret (bcrypt verify) The site's own domain
Site status disabled → 403 disabled → 403
Tenant isolation One index per site One index per site
Abuse limits Rate limit + plan limits Rate limit + monthly quota

Best practices for integrators

  1. Keep write credentials on the server. Store them in your platform's secret store. On WordPress, the options table is fine for server-side use; never print the credentials into HTML or JavaScript.
  2. Restrict the search key to your domains before going live.
  3. Rotate the keys if anything leaks, and treat the write secret like a database password.
  4. Verify on save. When a user enters credentials in your plugin, call the health endpoint to confirm they work before you store them.
  5. Fail safe. If Searcio cannot be reached, fall back to your platform's native search rather than showing an error.