An exchange API passphrase is a separate credential chosen when creating certain API keys; the API secret is the signing material used to authenticate requests. They are not interchangeable. The venue determines whether the passphrase is sent as its own header value or transformed first, so keep the key, secret, passphrase and required version together as one matched set.
A connection form can show three empty boxes that all look like passwords. Filling each with a valid-looking string is insufficient: each box has a different role, and every value must belong to the same issued credential. A replacement secret beside an old passphrase can be as unusable as a typing error.
Identify the saved value before inspecting the signature
For the shared-secret REST interfaces discussed here, separate four things:
| Item | Role | Common confusion |
|---|---|---|
| API-key identifier | Selects the registered credential at the exchange | Treating it as the signing secret |
| API secret | Computes request authentication using the venue's specified signing procedure | Sending it in the passphrase header |
| API passphrase | Additional credential associated with that issued API key | Substituting the exchange login or trading password |
| Request signature | Calculated output for the particular request representation | Saving it as though it were the permanent secret |
The passphrase in this article means an exchange API credential. A wallet recovery phrase and a password that unlocks an encrypted private-key file serve other purposes. Do not supply either merely because a form uses the word “passphrase.” Key-family compatibility is covered in the HMAC, RSA and Ed25519 comparison.
The secret normally remains inside the trusted signing system rather than being included as a literal request credential. That does not make the other fields safe to publish. Treat the complete credential bundle and authentication headers as sensitive, and keep them out of screenshots, support tickets and logs.
The same field name can require different wire values
These are scoped REST examples from official documentation reviewed on 23 October 2026, not a universal exchange standard.
| Interface | Passphrase header | Value required by the reviewed procedure |
|---|---|---|
| OKX V5 | OK-ACCESS-PASSPHRASE | The passphrase specified when the API key was created |
| Bitget UTA | ACCESS-PASSPHRASE | The passphrase set at API-key creation |
| KuCoin REST | KC-API-PASSPHRASE | Base64 output of HMAC-SHA256 over the passphrase using the API secret |
OKX documents the separate passphrase header alongside its secret-based request signature. See OKX V5 REST authentication. Bitget likewise distinguishes the saved passphrase from ACCESS-SIGN; its HMAC procedure signs the timestamp, uppercase method, path, optional query and body. See Bitget UTA authentication and signatures.
KuCoin adds a consequential distinction: computing the request signature and preparing the passphrase header are separate HMAC operations with different inputs. It also requires KC-API-KEY-VERSION, whose value comes from API Management. Follow the KuCoin REST authentication procedure for the issued key and current interface.
A connector that accepts the original KuCoin API passphrase may perform that transformation itself. Pasting an already transformed header value into its saved-passphrase field can cause a second transformation and authentication failure. Determine whether a field requests the original credential or an already prepared header; do not guess from the field's length.
These exchange examples establish authentication rules, not application support. KLINEO's current KuCoin connection guide documents Classic production credentials and their matching key version. It is the relevant product-specific reference before using that connection.
See where the passphrase does not belong
Consider a fictional OKX V5 account-read example, not a submitted request. Give its components the following labels:
- Timestamp:
2026-10-23T12:00:00.000Z - Method:
GET - Request path including query:
/api/v5/account/balance?ccy=BTC - Body: empty
Under the cited OKX procedure, concatenating those components produces this request-signing message:
2026-10-23T12:00:00.000ZGET/api/v5/account/balance?ccy=BTC
The API secret is the HMAC key, not another string appended to that message. The passphrase goes in its separate required header. Neither is a balance-query parameter, and an empty GET body is not replaced with the passphrase. The generated signature is then encoded as the venue requires.
This exercise reveals field placement without exposing any credential. It is deliberately not a reusable live request: no key, secret, passphrase or calculated signature is supplied. Other exchanges can use a different message layout, so copying this prefix order into another adapter would be an implementation error.
For clock windows, JSON serialization and URL encoding, use the timestamp and signature diagnostic. Those checks become meaningful after the credential roles and venue recipe are correct.
A matched-bundle troubleshooting worksheet
Imagine two fictional API-key sets, labeled Cedar and Flint. Each has its own identifier, secret and passphrase. The labels below are references to saved records, never real credential values.
| Observed configuration | What is wrong or still unknown | Useful next check |
|---|---|---|
| Cedar identifier, Flint secret, Cedar passphrase | Signing material belongs to another key | Compare secure configuration references and restore the complete Cedar bundle |
| Cedar identifier and secret, account login password in passphrase field | Wrong kind of credential | Retrieve the API-creation passphrase from its approved storage |
| Correct original values; raw passphrase sent by a KuCoin REST adapter | Header preparation disagrees with the reviewed procedure | Check passphrase HMAC/Base64 handling and the issued key version |
| Correct original values; transformed header pasted into a connector that transforms it again | Original and transmitted representations were confused | Restore the original passphrase through the connector's supported flow |
| Correct bundle and recipe; supported account read still fails | Another access or request condition remains possible | Preserve the provider code and inspect environment, timing, IP restrictions and permissions |
Change one cause at a time. “All fields are populated” is not evidence that they belong together. A non-secret record of the venue, account label, environment, API-key version, credential-record reference and connector version is more useful than a screenshot showing the actual fields.
A lost passphrase also has a lifecycle consequence. Bitget's cited setup guidance says it cannot be retrieved and the key must be recreated. Do not invent a replacement phrase in an application field: it will not change the value registered at the exchange. Plan the handover using the API-key rotation guide, retaining the account-state records needed to reconcile existing orders.
Define what a successful check proves
A supported authenticated read is a practical first acceptance check. Confirm the intended venue, account and environment in addition to a successful response. A response alone does not prove that every requested trade permission exists; review API-key permissions separately.
Once authentication works, an unexpected balance is a different investigation. The available versus total balance guide explains why funds can be visible yet unavailable for an order. Replacing a working passphrase cannot release reserved funds.
Likewise, a valid REST signature does not prove that private events arrive in business order. The order-event ordering guide covers how an authenticated connection can still deliver updates that require reconciliation.
Keep the acceptance record narrow: the matched credential set authenticated this supported read, against this interface and environment, at this time. That is enough to close the credential-role question while preserving the separate checks that trading operation requires.
Editorial method: Prepared with AI assistance on 23 October 2026 from cited exchange documentation and KLINEO's public KuCoin guidance. The request decomposition and credential-bundle worksheet are original fictional examples. No live credentials, authenticated requests or trades were used.