# Authentication

> Secret keys, test and live environments, and where a key may (and may not) live.

Every API request carries a **secret key** as a bearer token:

```http
Authorization: Bearer dz_test_sk_...
```

A key is bound to one business and one environment. You never send a business id — the key alone decides which business a request belongs to.

| Prefix | Environment | Moves real money? |
| --- | --- | --- |
| `dz_test_sk_` | Test | No — sandbox only |
| `dz_live_sk_` | Live | Yes |

Test and Live are completely separate: a test key can neither see nor change a live payment, and the reverse. Create keys under **Developers → API keys**; the secret is shown **once**. Lost it? Rotate the key.

> **Warning:** **Secret keys belong on your server.** Never put one in browser JavaScript, an Android APK, an iOS app, a React Native or Flutter bundle, or a distributed desktop binary. Anything shipped to a device can be extracted. A test key can't move real money, but treat it as a secret too.

## Where the key lives

```text
WEBSITE / SERVER
your server ──(secret key)──▶ Devzity API ──▶ checkout_url ──▶ customer

ANDROID / iOS / REACT NATIVE / FLUTTER
mobile app ──▶ YOUR backend or serverless function ──(secret key)──▶ Devzity API
mobile app ◀── checkout_url ── your backend        (the app only opens the URL)
```

The same shape covers a serverless function or a Next.js route: the function holds the key, the app never does.

> **Note:** **"I only have an app, no backend."** You still must not put the key in the app. You need one tiny trusted endpoint that creates the payment — see [I only have an app](https://docs.devzity.com/v1/mobile-backend.md).

## Scopes

A key has `payments:read` (retrieve and list) and/or `payments:write` (create and cancel). They are independent. A request outside a key's scopes returns `insufficient_scope` (403).

## Failures

An unknown, malformed or revoked key returns `401 invalid_api_key`. Requests are rate limited per key (60 per minute by default); a `429` includes a `Retry-After` header. See [Errors](https://docs.devzity.com/v1/errors.md).