Skip to Content
GuidesAPI keys

API keys

Every project carries an API key pair — a public Project ID (X-Project-Id) and a secret API secret (TXNOD_API_SECRET) used to HMAC-sign every REST request to the TxNod API. The secret is also the value the SDK passes as apiSecret when constructing TxnodClient. This page covers the two operations you do on the key pair: generation and rotation.

Generate a new key

  1. Open Settings → API Keys in the dashboard.
  2. Click Generate new key. The dashboard shows the new secret exactly once in a modal — copy it immediately into your secrets manager (1Password, Doppler, AWS Secrets Manager, or equivalent). The plaintext is never readable again; the server persists only an HMAC-keyed hash of the secret.
  3. Production secrets begin with the production prefix; sandbox secrets begin with sk_sandbox_. The prefix is a stable contract — log-redaction patterns and .env leak detectors can match on it.

The secret_hash column is populated via SHA-256 at mint time and compared with timingSafeEqual from node:crypto at verify time — a constant-time compare that closes timing oracles.

Rotate without downtime

Rotation lets you swap a leaked or aging secret without dropping in-flight requests. Both the old and the new key are valid simultaneously during the rollover window:

  1. Generate a new key (steps 1–3 above).
  2. Deploy the new secret to your partner application. Both keys are valid simultaneously during the rollover.
  3. Monitor the API Keys page’s Last used column for the old key. Wait until it has been idle for at least 30 minutes (or until your deployment’s slowest retry cycle has elapsed).
  4. Click Revoke on the old key. Any in-flight request still signed with the revoked secret fails with key_revoked (403).
  5. If a rotation goes wrong and you need to undo the revoke: you cannot. Generate a fresh key (step 1) and repeat the rollover — revocation is one-way.

Personal Access Tokens vs API keys

The project API secret signs REST requests from your partner application. Personal Access Tokens (PATs) are a separate credential class used by the TxNod MCP server and developer tooling — see Personal Access Tokens for the scopes-and-expiry model and the txnod_pat_<...> wire format.

BillingPersonal Access Tokens