Skip to content

API essentials

A key to your integration.

Authenticate requests and keep your credentials private.

Every data endpoint authenticates with an API key. Present it in either header — whichever fits your client:

Code example
curl https://api.lottevo.com/v1/lotteries \
  -H 'Authorization: Bearer lv_a1b2c3d4e5f6_…'

curl https://api.lottevo.com/v1/lotteries \
  -H 'X-Api-Key: lv_a1b2c3d4e5f6_…'

A key looks like lv_{prefix}_{secret} (a sandbox key: lv_test_{prefix}_{secret}). The prefix is public by design: it identifies the key in logs and support requests without revealing the secret half. The full key exists only on the response that issued it — afterwards only its hash is stored, so a key you lose has to be replaced.

Issuing a key

Sign up, then mint a key with the scopes you need. A few rules are worth knowing before you reach the form:

  • The plan belongs to the account, not the key. Your first key (other than a sandbox key) starts a 14-day free trial; after that every key runs on the plan you buy from Billing. Once the trial ends without a plan, plan keys answer every request with 402 subscription_required (sandbox keys keep working).
  • The trial covers one game. The first key names it: any game, your own country's included, except those drawn every 30 minutes or more often (Keno and similar). It stays the trial's game until the trial ends, whatever happens to the key; subscription.trial_lottery_code on your profile says which.
  • A plan with a lottery cap has no "everything" state. On Developer and Starter the key must name the games it covers, and an unnamed selection is refused rather than silently meaning the whole catalogue.
  • A key may carry an expiry, after which it stops working rather than lingering.

Keys in a browser

A key can be pinned to a list of origins. Such a key may carry read scopes only, and that is not a UI preference — the origin check is a courtesy a non-browser caller skips by omitting the header, so a browser-pinned key must not be able to change anything.

Even so, a key in a page is a key every visitor can read and spend. For anything beyond a demo, call the API from your own server.

Verifying a key works

Code example
curl https://api.lottevo.com/v1/account -H 'X-Api-Key: lv_a1b2c3d4e5f6_…'
Code example
{
  "data": {
    "key": { "name": "Production", "prefix": "a1b2c3d4e5f6", "sandbox": false, "scopes": ["catalog:read", "draws:read"], "lottery_codes": ["EU-001"], "history_from": "2026-06-22T09:30:00+00:00", "history_until": null, "expires_at": null },
    "plan": { "name": "trial", "requests_per_day": 1000, "requests_per_minute": 30, "history_days": 90, "history_delay_days": null, "history_draws": null, "trial_ends_at": "2026-10-01T08:12:00+00:00" },
    "usage": { "date": "2026-09-20", "requests": 42, "remaining": 958, "resets_at": "2026-09-21T00:00:00+00:00" }
  }
}

lottery_codes is null when the key carries the whole catalogue, and a list when it does not. That distinction matters: null is not "none".