For AI agents: this page is also available as Markdown at /docs/access-control.md. Every docs page is: add .md to its URL. llms.txt lists them all.
API keys, roles and rate limits
Every request to WarpSearch is authenticated. There is no anonymous access, including to the compatible endpoints. You authenticate with an API key, and the key's role decides what the request may do. This page covers keys, roles, visibility and rate limits.
#Authenticate
Send the key as a bearer token:
curl https://api.warpsearch.io/v1/collections \
-H "Authorization: Bearer $WARPSEARCH_API_KEY"
Keys look like ws_live_.... The same key works on /v1, on the Elasticsearch, OpenSearch and
Solr compatible endpoints, and on the MCP server at /mcp. For clients that cannot set a bearer
header, the key is also accepted as X-API-Key: <key>, as Authorization: ApiKey <key>, or as the
password of HTTP Basic with an empty or any username.
Keep keys out of source control and browser code. Anyone holding a key has its role.
Missing or invalid credentials answer 401. Repeated failures from one address are throttled
with 429 too_many_auth_failures, so a script with a wrong key should stop rather than retry in
a tight loop.
#Roles
Each key has one of three roles, and so does each member of your organization.
| Role | Can do |
|---|---|
viewer |
List and describe collections, search, count, translate, get a document by id, read usage. |
editor |
Everything a viewer can, plus index, replace and delete documents, and refresh. |
admin |
Everything an editor can, plus create, change and delete collections, change mappings, force merge, and manage members and API keys. |
Roles are cumulative. A refused call answers 403 forbidden, and the message names the role you
needed, for example that the key lacks the admin role on a collection.
Pick the lowest role that works: a search service gets viewer, a loader gets editor, and only
provisioning scripts get admin.
#Create and revoke keys
Create keys in the console under API keys:
- Create a key, give it a descriptive name (for example
ci-loader) and pick a role. - Copy the secret. It is shown once and cannot be retrieved later.
- To revoke, delete the key in the same place. Revocation takes effect within a few minutes everywhere.
Rules to know:
- A key's role can never be higher than the role of the person who created it.
- A key acts only in the organization it was created in.
- A key stops working if the person who created it leaves the organization, so use a dedicated member for long-lived automation.
- Keys cannot create other keys or send invitations. Both need a signed-in console session, so a leaked key cannot mint credentials that outlive its revocation.
- Editors manage their own keys. Admins see and manage all keys in the organization.
Agents get keys through a consent flow instead of copy and paste: the agent registers, you approve in the console and choose the role, and the key is created in your name. See Guide for AI agents.
#Members and invitations
Admins invite people by email from the console and choose a role. The person accepts the invitation by link, and may belong to several organizations. Removing a member also revokes their keys in your organization.
Not supported: single sign-on with your own identity provider.
#Visibility
A collection you hold no role on does not exist as far as your key can tell. It is absent from
listings, and every route answers 404 exactly as it does for a name that was never created. A
collection you can see but cannot use for the request answers 403 with the role you need.
GET /v1/auth/me shows who the key belongs to, its role on each visible collection, its
permissions and its effective rate limit. It is the first thing to call when a request is refused.
#Rate limits
Requests are limited by a token bucket per organization, based on your plan, and your plan also
sets how many requests may run at the same time. A request over either limit answers 429 with a
Retry-After header:
| Code | Meaning |
|---|---|
rate_limited |
You exceeded your requests per second. Retry after Retry-After. |
too_many_concurrent_requests |
Too many requests are in flight at once. Retry in a moment. |
too_many_auth_failures |
Too many failed authentications from your address. |
Responses carry RateLimit-Limit and RateLimit-Remaining headers, so a client can slow down
before it is refused. The limits depend on your plan: see Pricing for the
free tier and /pricing for paid plans.
How to behave:
- On
429, wait forRetry-Afterand retry with some jitter. Do not retry in a tight loop. - Batch writes instead of sending many small requests. See Ingesting documents.
- Debounce search-as-you-type, and cache repeated queries.
- Cap an agent's retries and tool calls, because it can issue queries faster than a person.
A plan can count the limit per client address instead of per organization, which matters when many
end users share one key. GET /v1/auth/me reports the effective limit.
#Usage and plan
GET /v1/usage returns your plan, how many collections you have against the limit, and stored
documents and bytes. The call needs a key with permission to view usage; the console shows the same
numbers. For the limits themselves, see Limits and errors.
#Good practice
- One key per service and environment, so you can revoke one without touching the rest.
- Keep browser-facing search behind your own server, or use a
viewerkey that can only search. - Rotate keys by creating the new one, deploying it, then deleting the old one.
- Check each key's last-used time in the console to find keys that nothing uses any more.