Authentication and API keys

Every request to the Lazy Embedded API must carry your platform’s API key as a bearer token.

Sending the key

Put the key in the Authorization header, after the word Bearer and one space:

curl https://embedded-api.lazyinvoice.co.il/v1/businesses \
  -H "Authorization: Bearer $LAZY_API_KEY"

The word Bearer is case-sensitive. A request with no key, a malformed header, or a key Lazy does not recognize gets 401 Unauthorized with the error code unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "request_id": "q8Zr1Ndk2vLp0Xw7HcYt3Rb9Fs6Mj4Ge5Ua1Ki8Oy2Wn0Tz7Ql3Px=="
  }
}

Some request checks run before the key check, so a request with no key can get 400 validation_error instead of 401. See Errors.

What a key can do

A key belongs to your platform, not to one business. It can read and change every business your platform created, and no business of any other platform. A request for another platform’s business gets 404 not_found, the same as for a business that does not exist.

Keep keys on your servers only. Anyone holding a key can create, change and delete your businesses and buy extras that Lazy bills to your platform.

Getting a key

Lazy issues API keys on request. Ask your Lazy contact for a key, and say what it is for so you can tell your keys apart later. Your platform can hold more than one key at a time, which lets you rotate keys without downtime:

1. Ask Lazy for a new key.
2. Deploy the new key to your servers.
3. Ask Lazy to revoke the old key.

Revoking a key

Ask Lazy to revoke a key you no longer use or that may have leaked. After revocation, the key can keep working for up to 5 minutes, because Lazy’s servers remember a recently verified key for that long. After 5 minutes every request with it gets 401 unauthorized.