# Authentication

Your API key is a bearer token. Where to get one, how to send it, and what happens if it leaks.

Every endpoint in this reference needs your API key. You send it as a bearer token in the `Authorization` header:

```bash
curl -X GET "https://api.leapa.co/v2/invoices" \
  -H "Authorization: Bearer $LEAPA_API_KEY"
```

A request without the header, or with a key the server does not recognise, is answered with `401 Unauthorized`. A valid key that is not allowed to do the thing you asked gets `403 Forbidden`.

## Getting a key

Keys live in your Leapa dashboard, under **Settings → API Keys**. Click **Create Secret Key**, name it after the thing that will use it, and copy the value. [Create your account](/docs/web-application/create-your-account#generate-api-keys) walks through the screens.

You are shown the full key once, at creation. Leapa stores a hash of it and cannot show it to you again, so put it somewhere your application can read before you close the dialog.

## What the key carries

The key is a JSON Web Token, a signed string with a few facts baked into it. Two of them decide what your requests can do:

- **Your merchant account**, which is why no endpoint asks you which merchant you are. `POST /ips/onboard-merchant` onboards *you*, and `GET /customers` returns *your* customers.
- **A currency account.** A key is issued against one currency. A key issued for BIF cannot charge in USD.

Because the merchant is read from the key, an endpoint that takes no parameters at all still knows exactly whose data to act on.

## Keep it on your server

Your API key can move money and read every customer you have. It is a server-side credential, and the rules that follow from that are absolute:

<Callout type="danger" title="Never put an API key in a browser">
	Anything in your page source, your JavaScript bundle, or a mobile app
	binary is readable by anyone who visits. That includes a key passed through
	a build-time environment variable that your bundler inlines. Keys belong on
	a server the public cannot read.
</Callout>

Practical version:

- Read it from an environment variable or a secret manager, never from a file in your repository.
- Keep it out of URLs and query strings, because those end up in server logs, browser history and referrer headers.
- Give each application its own key, so revoking one does not stop the others.
- Rotate a key the moment you suspect it has been seen. Create the replacement, deploy it, then delete the old one.

## The widget is the exception, and it is not one

The [payment widget](/docs/widgets/integration) takes an `api-key` attribute in your page’s HTML, which looks like it contradicts everything above. It does not: the widget key is a separate, publishable key that can only start a payment for an invoice you already created. It cannot list your customers or move your balance.

The keys documented on this page cannot be used that way. If a key from **Settings → API Keys** ever appears in a page’s source, treat it as compromised and rotate it.

---

_Generated from the Leapa documentation at leapa.co/docs._