Skip to content
Create account

API reference · v1

Authentication & scopes

How the XEYE API authenticates: the X-API-Key header, per-key scopes, expiry, rotation and rate limits.

The X-API-Key header

Every request carries the X-API-Key header with a key created in the console (API keys). There is no OAuth and no token to refresh: the key is sent as is, always over HTTPS. The backend stores only its hash, and a deleted key stops working on the next request.

http
GET https://api.xeye.es/v1/me
X-API-Key: xeye_Wq3kAbcdefghijklmnopqrstuvwxyz01

A key belongs to one account: it sees and modifies only the lists of that account. A resource of another account answers 404, never 403, so it never reveals that it exists.

Scopes: what each key can do

When you create a key you choose its scopes. Each endpoint requires a specific one; without it, 403 API_KEY_SCOPE. Write scopes imply the read scope of the same resource. Keys created before the management API only have search.

ScopeGrantsImplies
searchSearch the public lists of the account (POST /search, POST /target).—
lists:readRead lists and elements.—
lists:writeCreate, update and delete lists and elements.lists:read
trainings:readRead trainings, estimates and models.—
trainings:writeLaunch and relaunch trainings (they consume credit).trainings:read

The console offers two presets: “Search only” (search), for the key your website uses, and “Full management” (all scopes), for the process that syncs the catalogue. Safest is one key per use.

Today the search service accepts any key of the account for public lists, with or without the search scope; the scope will be enforced there too in an upcoming release. Create keys with the right scopes from now on.

Expiry

Optionally, a key expires on a fixed date (1 to 3650 days after creation). An expired key answers 401 API_KEY_EXPIRED; expiry cannot be edited: create another key and delete the old one. The console shows the date and the last use of each key.

Checking a key: GET /me

Key identity

GEThttps://api.xeye.es/v1/meScope: any key

Returns the key id and prefix, its effective scopes (implied ones included), its expiry and the account id. It requires no scope: use it to verify the setup before touching data.

Request

bash
curl -X GET https://api.xeye.es/v1/me \
  -H "X-API-Key: $XEYE_API_KEY"

Response

200 OK · application/json
{
  "api_key_id": 7,
  "prefix": "xeye_Wq3kAbc",
  "scopes": ["lists:read", "lists:write", "trainings:read", "trainings:write"],
  "expires_at": null,
  "user_id": 3
}

Rotation and revocation

Rotating means creating a new key with the same scopes, deploying it and deleting the old one: both coexist meanwhile. Deleting a key revokes it instantly. If a key leaks, delete it and review the search history of your lists.

Rate limits

The management API allows 300 requests per minute per key. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the next window); once exhausted you get 429 RATE_LIMITED with Retry-After.

In addition, 30 failed authentications per minute from the same IP block that IP for the rest of the minute (429), before anything is looked up. Search has its own per-account quota: 120 per minute, shared by all keys.

429
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23

{
  "status": 429,
  "error": "Too Many Requests",
  "code": "RATE_LIMITED",
  "message": "Too many requests, try again in 23 seconds"
}

Recommendations

  • Keep the key in a server-side environment variable; never in the repository or in code that reaches the browser.

  • One key per integration and environment, with the minimum scopes: the website key only search; the sync key without search.

  • Set an expiry on test and third-party keys, and review the last use of each one in the console.

Next: Lists