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

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# API keys and credential security

> How to store, separate, rotate, and revoke Bitnob credentials so a leaked secret cannot move funds.

A Bitnob credential gives access to value, not only to data. A leaked `CLIENT_SECRET` lets the holder sign requests as you, and money movement does not reverse.

This guide covers how to hold credentials across development, staging, production, and CI. It also covers what to do when one leaks.

## Understand what you hold

Your credentials are a pair.

| Value | Purpose | Exposure |
| - | - | - |
| `CLIENT_ID` | Identifies your account. Sent in the `X-Auth-Client` header. | Not secret. It appears in every request. |
| `CLIENT_SECRET` | Signs the request. Never transmitted. | Secret. Treat it as the key to your balances. |

The secret never goes over the wire. You use it to compute an HMAC signature, and we recompute the same signature to verify the request. See [Authentication](https://www.bitnob.dev/api-reference/authentication/authentication.md#overview).

> [!NOTE]
>
> The Bitnob Enterprise API uses a different credential, an `X-API-Key` header. The rules on this page apply to it as well.

## Keep credentials out of source code

Never write a secret into a file you commit, even in a private repository. Repository history keeps the value after you delete the line.

**Do not do this:**

```js theme={null}
const clientSecret = "5f4dcc3b5aa765d61d8327deb882cf99";
```

**Do this:**

```js theme={null}
const clientSecret = process.env.BITNOB_CLIENT_SECRET;
```

Add your environment files to `.gitignore` before the first commit.

## Separate the two secrets

Your `CLIENT_ID` is the same in sandbox and production. Only the `CLIENT_SECRET` differs, and the secret you sign with decides whether a request moves real money.

Name the two variables so that no one confuses them:

```bash theme={null}
BITNOB_CLIENT_ID=yourClientId
BITNOB_SANDBOX_CLIENT_SECRET=yourSandboxSecret
BITNOB_PRODUCTION_CLIENT_SECRET=yourProductionSecret
```

> [!WARNING]
>
> Never load a production secret into a development or staging process. There is no separate host to protect you, because both environments use `https://api.bitnob.com`.

## Keep credentials out of client applications

A credential must live only on a server you control.

Do not place one in:

* A browser application. Anyone can read it from the network tab.
* A mobile application. Anyone can extract it from the package.
* Any client-side JavaScript bundle.

Route requests through your own backend. Your client application calls your server, and your server calls Bitnob.

![api-key-illustration](https://mintcdn.com/bitnob/5PGS9OuNC096evyI/images/api-key-illustration.png?fit=max\&auto=format\&n=5PGS9OuNC096evyI\&q=85\&s=866abc6ef714115d0dfb39db458ed348)

## Use a secret manager in production

Environment files are acceptable in development. In production, use a manager that injects secrets at runtime:

* AWS Secrets Manager
* GCP Secret Manager
* HashiCorp Vault
* Doppler, Infisical, or 1Password Secrets Automation

These tools store secrets encrypted, record who read them, and support versioned rotation.

## Rotate on a schedule

Rotate every 60 to 90 days. Rotate immediately when:

* An engineer leaves the team.
* A credential appears in a log, a ticket, or a screenshot.
* You give a contractor or a partner access.

Rotate without downtime by running two keys briefly:

**1. Create the new key**

Create a second key in **Settings** > **API Keys**. Both keys work at the same time.

**2. Confirm the new key**

Call `/api/whoami` with the new secret. See [Validate authentication](https://www.bitnob.dev/api-reference/authentication/usage-examples.md#validate-authentication).

**3. Deploy the new key**

Roll the new secret out to every service that signs requests.

**4. Revoke the old key**

Revoke the old key only after traffic on it stops.

## Scan for leaked credentials

Run a scanner on every commit. These tools catch a secret before it reaches a shared branch:

* [GitGuardian](https://gitguardian.com/)
* [TruffleHog](https://github.com/trufflesecurity/trufflehog)
* GitHub Advanced Security

## Redact credentials from logs

Never log a full secret, an `Authorization` header, or an `X-Auth-Signature` value. Redact them before the log line is written.

```javascript theme={null}
app.use((req, res, next) => {
  const redact = ["authorization", "x-auth-signature", "x-api-key"];
  for (const header of redact) {
    if (req.headers[header]) {
      req.headers[header] = "REDACTED";
    }
  }
  next();
});
```

Log the `CLIENT_ID` and the `correlation_id` instead. Both identify the request without exposing the secret.

## Watch for misuse

Track your own call volume, so that unusual activity is visible:

* Total requests per minute.
* Requests per endpoint.
* Failures by status code.
* Source region, if your traffic should come from one place.

Alert when traffic rises far above its normal level, or when a service calls an endpoint it has never called before. A simple alert to a chat channel is enough to start.

## Respond to a leak

Assume that a credential will leak one day, and make the response fast.

**1. Revoke the key**

Revoke it in the dashboard. Revocation takes effect immediately.

**2. Create and deploy a replacement**

Create a new key and roll it out.

**3. Review activity**

List transactions for the exposed period and compare them against your own records. See [Observability, logging, and traceability](https://www.bitnob.dev/docs/getting-started/api-best-practices/observability-logging-and-traceability.md).

**4. Contact support**

Report any transaction you cannot account for. Quote its `correlation_id` and its `reference`.

## Do not reuse Bitnob credentials internally

Your own services need to authenticate to each other. Do not use your Bitnob credentials for that.

Issue short-lived signed tokens instead, carry only the claims each service needs, and verify them inside your own infrastructure. This keeps the blast radius of an internal leak inside your system.

## If you resell access

If you build a multi-tenant product on top of Bitnob, your tenants need their own credentials, not yours. Issue per-tenant keys with an expiry, a version prefix, and a self-serve revoke action.

A single gateway service in front of Bitnob gives you one place to rotate keys, apply rate limits, and keep tenants isolated.

## Summary

| Practice | What it prevents |
| - | - |
| Keep secrets out of source code | A permanent leak in repository history |
| Separate sandbox and production secrets | A test job moving real money |
| Keep secrets server-side | Extraction from a browser or a mobile package |
| Use a secret manager | Unaudited access to production values |
| Rotate on a schedule | Long-lived exposure after staff changes |
| Scan commits | A secret reaching a shared branch |
| Redact logs | Exposure through your own observability tools |
| Watch call volume | Undetected use of a stolen credential |

## Next

Continue to [Idempotency and references](https://www.bitnob.dev/docs/getting-started/api-best-practices/idempotency-and-reference-integrity.md), which covers how to make retries safe.


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