# 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:

```bash
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`:

```json
{
  "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](https://developers.lazyinvoice.co.il/embedded/errors/#validation-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`.