Authentication

Authenticate OptimAI Search API requests with an API key.

Create or manage API keys at search.optimai.network/api-keys.

Send API keys in the X-API-Key header.

X-API-Key: sk_live_...

X-API-Key is the recommended header. For compatibility, the backend also accepts Authorization: Bearer sk_..., but do not use both headers in one request.

Key types

Prefix	Intended use	Important behavior
`sk_live_`	Normal production API access	Uses the normal production policy and does not expire by default.
`sk_test_`	Active external-partner testing	Requires an active partner record, can expire, and may have lower rate and concurrency limits.

Test keys are a logical policy mode, not a separate sandbox. They use the same API infrastructure and account-level credit balance as live keys. Usage reports can still distinguish requests by API key. The backend checks the stored key type and partner status; changing only the visible prefix does not convert a live key into a test key.

Scopes are assigned to each key. Give a key only the operation scopes the calling service needs (search, scrape, seed, or crawl, each with create, read, and cancel where applicable).

Server-side only

Keep keys on your server. Browser clients should call your backend, and your backend should call OptimAI Search.

await fetch("https://api-onchain.optimai.network/external/v1/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.OPTIMAI_API_KEY ?? "",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "What is OptimAI Search?" }),
})

Rotation

Rotate keys when a team member leaves, a key is exposed, or an application boundary changes.

Common mistakes

Sending Authorization: Bearer ... instead of X-API-Key.
Reading the key from a client-side NEXT_PUBLIC_ or VITE_ variable.
Forgetting to set the key in the production runtime after local testing.