Getting started
Authentication & security
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" .-> BrowserWrite credentials (ingest)
Used for indexing, from server to server. Never expose these in a browser.
- Write key (
wk_…) identifies the site. Send it in theX-Write-Keyheader. - Write secret is the password half. Send it in the
X-Write-Secretheader.
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/jsonSecurity 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 akeyquery parameter or in anX-Search-Keyheader.
# 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_xyzThe 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
Originheader must be the site's domain, with or withoutwww.. A request from any other website, another subdomain such asen.shop.acme.comincluded, is rejected with403 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
Originheader. - 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 inX-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 withoutAccess-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_urlcan be connected automatically only once. A repeat attempt with a differentidempotency_keyis rejected with409, which is what stops anyone from claiming a domain they do not control. - Email ownership is never assumed. If
admin_emailbelongs 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
- 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.
- Restrict the search key to your domains before going live.
- Rotate the keys if anything leaks, and treat the write secret like a database password.
- Verify on save. When a user enters credentials in your plugin, call the health endpoint to confirm they work before you store them.
- Fail safe. If Searcio cannot be reached, fall back to your platform's native search rather than showing an error.