API keys and credential security

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.

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:

const clientSecret = "5f4dcc3b5aa765d61d8327deb882cf99";

Do this:

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:

BITNOB_CLIENT_ID=yourClientId
BITNOB_SANDBOX_CLIENT_SECRET=yourSandboxSecret
BITNOB_PRODUCTION_CLIENT_SECRET=yourProductionSecret

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.

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:

Create the new key

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

Confirm the new key

Call /api/whoami with the new secret. See Validate authentication.

Deploy the new key

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

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
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.

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.

Revoke the key

Revoke it in the dashboard. Revocation takes effect immediately.

Create and deploy a replacement

Create a new key and roll it out.

Review activity

List transactions for the exposed period and compare them against your own records. See Observability, logging, and traceability.

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

Continue to Idempotency and references, which covers how to make retries safe.

Get started

Bitcoin

Stablecoins

Trading

Payouts

Card issuing

Virtual accounts

API keys and credential security

Understand what you hold

Keep credentials out of source code

Separate the two secrets

Keep credentials out of client applications

Use a secret manager in production

Rotate on a schedule

Scan for leaked credentials

Redact credentials from logs

Watch for misuse

Respond to a leak

Do not reuse Bitnob credentials internally

If you resell access

Summary

Next

​Understand what you hold

​Keep credentials out of source code

​Separate the two secrets

​Keep credentials out of client applications

​Use a secret manager in production

​Rotate on a schedule

​Scan for leaked credentials

​Redact credentials from logs

​Watch for misuse

​Respond to a leak

​Do not reuse Bitnob credentials internally

​If you resell access

​Summary

​Next

Understand what you hold

Keep credentials out of source code

Separate the two secrets

Keep credentials out of client applications

Use a secret manager in production

Rotate on a schedule

Scan for leaked credentials

Redact credentials from logs

Watch for misuse

Respond to a leak

Do not reuse Bitnob credentials internally

If you resell access

Summary

Next