> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate your API requests with API keys and Bearer tokens.

All Simiz API requests require authentication via your **secret API key** passed as a Bearer token.

## API key types

| Key type        | Prefix                          | Environment | Usage                        |
| --------------- | ------------------------------- | ----------- | ---------------------------- |
| Test secret key | `smz_test_sk_`                  | Sandbox     | Development & testing        |
| Live secret key | `smz_live_sk_`                  | Production  | Real transactions            |
| Publishable key | `smz_test_pk_` / `smz_live_pk_` | Both        | Client-side (checkout forms) |

<Warning>
  **Secret keys** must never be exposed in client-side code, Git repos, or logs. Use publishable
  keys for client-side operations.
</Warning>

## Authenticating requests

Include your secret key in the `Authorization` header:

```bash
curl https://api.simiz.io/v1/transactions \
  -H "Authorization: Bearer smz_test_sk_xxxxxxxxxxxx"
```

## Managing API keys

1. Go to **Dashboard → Settings → API Keys**
2. Your keys are displayed (secret keys are partially hidden)
3. Click **Regenerate** to generate new keys
4. The old key is immediately revoked

## API key scopes

<Frame caption="Route access is default-deny: the scope guard serves a route (200) only if the key carries an allowed scope, otherwise it rejects the request (403). The key prefix selects the environment.">
  <img src="/images/authentication-scopes.svg" alt="Diagram: an API request with a Bearer key reaches the Simiz default-deny scope guard; if the key has an allowed scope the route is served (200), otherwise it is rejected (403). Key prefixes map test keys to sandbox and live keys to production." />
</Frame>

* Each API key now includes explicit scopes.
* Route access is **default-deny** for API-key auth unless the route is marked with allowed scopes (or explicitly public).
* `PUBLISHABLE` keys can only receive publishable-safe scopes.

<Note>
  After regenerating a key, update your application immediately. The old key stops working as soon
  as the new one is generated.
</Note>

## Sandbox vs Production

The API key prefix determines the environment:

* **`smz_test_sk_`** → All requests go to the sandbox (no real money)
* **`smz_live_sk_`** → All requests go to production (real transactions)

The base URL is the same for both: `https://api.simiz.io/v1/`

<Tip>
  Use **environment variables** to switch between sandbox and production without code changes:

  ```bash
  # .env.development
  SIMIZ_SECRET_KEY=smz_test_sk_xxxxxxxxxxxx

  # .env.production
  SIMIZ_SECRET_KEY=smz_live_sk_xxxxxxxxxxxx
  ```
</Tip>

## Best practices

* **Use environment variables** — Never hardcode API keys
* **Restrict key permissions** — Use keys with the minimum required permissions
* **Rotate keys regularly** — Regenerate keys periodically
* **Monitor usage** — Check the Dashboard for unusual API activity