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

# Authentication

> Create, store, restrict, rotate, and revoke Sakawave API keys.

Business API requests use bearer API keys. A key starts with `sk_test_` in sandbox or `sk_live_` in live.

```http theme={null}
Authorization: Bearer sk_test_your_key_here
```

## Key lifecycle

The dashboard displays the complete secret only when a key is created or explicitly rotated. Sakawave stores a verifier rather than the complete credential, so a lost secret cannot be retrieved. Create or rotate a key, update your secret store, verify the replacement, then revoke the old key.

Recommended controls:

* Keep keys in a secrets manager, never in client-side code or source control.
* Use separate keys for separate services and environments.
* Set an expiry date when the dashboard supports your operational cadence.
* Apply the narrowest IP allowlist possible. An empty allowlist permits any source address.
* Rotate immediately after suspected exposure or team ownership changes.
* Treat revocation as irreversible.

IP allowlists accept exact IPv4 or IPv6 addresses, CIDR ranges, `*`, and trailing IPv4 wildcards such as `203.0.113.*`. Avoid `*` for live credentials.

## Environments

The environment embedded in the key must match the API deployment. A test key sent to live—or a live key sent to sandbox—is rejected with `INVALID_API_KEY`.

## Authentication failures

Sakawave deliberately returns the same `401` response for an invalid, inactive, expired, environment-mismatched, or IP-blocked key.

```json theme={null}
{
  "code": "INVALID_API_KEY",
  "message": "Invalid or inactive API credentials."
}
```

This response does not reveal which check failed. Confirm the environment, key status, expiry, and caller IP locally before contacting support.

## Scope contract status

<Warning>
  Scope behavior is not yet a public contract. Current issuance stores scopes, but business API authentication does not enforce them. Do not rely on a selected scope to prevent an otherwise valid key from calling an endpoint.
</Warning>

Until enforcement and intended delegation behavior are aligned, use separate keys, network restrictions, and service-level secret isolation as the effective controls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.