Authentication

Skirre uses API keys to authenticate requests. Every request to the /v1/ API must include a valid key in the Authorization header.

API Keys

API keys are created through the Keys API or the Skirre dashboard. Each key is a string starting with a type prefix, followed by 32 random alphanumeric characters.

text
# Admin key
sk_search_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

# Search key
pk_search_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345
Keys are shown only once
The full API key is returned only at creation time. Skirre stores a SHA-256 hash of the key, so it cannot be retrieved later. Copy and store it securely immediately after creation.

Key Types

ParameterTypeDescription
Admin (sk_search_live_) optionalsecretFull access: create/delete indices, manage documents, update settings, create keys. Use server-side only. Never expose in client code.
Search (pk_search_live_) optionalpublishableSearch and read access only. Safe to use in browser or mobile apps. Cannot create or modify indices, documents, settings, or keys.

Using Keys

Include the key in the Authorization header using the Bearer scheme:

text
curl -X POST https://search.example.com/v1/indices/products/search \
  -H "Authorization: Bearer pk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "q": "shoes" }'

With the TypeScript SDK, pass the key when creating the client:

text
import { Skirre } from '@skirre/sdk';

const skirre = new Skirre({
  apiKey: 'pk_search_live_...',
  baseUrl: 'https://search.example.com',
});

CORS Origins

Each API key can optionally restrict which browser origins are allowed to make requests with it. This is an additional security layer for search keys used in frontend applications.

text
# Create a key locked to specific origins
curl -X POST https://search.example.com/v1/keys \
  -H "Authorization: Bearer sk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Frontend",
    "key_type": "search",
    "allowed_origins": "["https://example.com", "https://staging.example.com"]"
  }'

When allowed_origins is set, Skirre validates the request's Origin header against the list. Requests from unlisted origins are rejected with a 403 Forbidden.

Security Best Practices

  • Never expose admin keys in client-side code. Admin keys can create and delete indices, modify documents, and manage other keys. Keep them server-side.
  • Use search keys for frontend search. Search keys can only read data and perform searches, making them safe for browser or mobile apps.
  • Set CORS origins on search keys. Lock each search key to the domains that should be allowed to use it.
  • Rotate keys periodically. Create a new key, update your application, then revoke the old one.
  • Use separate keys per environment. Don't share keys between production and staging.