Skip to main content
Account links calls use a bearer token from your partner client, and order reports use a signature instead.
This page covers how you authenticate to Bilt. For how Bilt authenticates to you, see Credentials for the endpoints you host.
Authenticate every account links call with a partner access token, minted by your partner client with the client credentials grant.
  • Send it as Authorization: Bearer <token>, and on no other header.
  • Use the same partner client for every Bilt API, and never send a member access token.
Your credential identifies you, so no request carries a partner ID, and you see only your own links. A bad credential returns 401 with no detail. A sudden 401 means your credential was rotated or disabled, so contact Bilt. Bilt rotates keys with you, as a configuration change. Create a link also requires the id_token as a second credential.

​
Legacy API key

The x-api-key header is being retired. Do not send it with a bearer token. A rejected token does not fall back to the key.

​
Signatures for order reports

Order reports carry no token. You sign each request with your Ed25519 private key and send your key ID in X-Bilt-Key-Id. Your key identifies you, so no URL or body carries a partner ID, and partners never see each other’s orders. See Sign your requests.

​
Secrets on your server

Make every call to Bilt from your backend. API keys, client secrets, access tokens, signing private keys, code_verifier values, and id_token values never reach a browser or mobile app.
  • Use TLS 1.2 or later. Your redirect URI uses HTTPS. Plain http://localhost is allowed only in development.
  • Keep secrets in a secret store. Cache your access token in memory, not on disk or in logs.
  • Enforce state and PKCE with S256. state blocks a forged callback. PKCE blocks an intercepted code, and the single-use code blocks replay.

​
Logging

Never log id_token values, access tokens, the Authorization header, authorization codes, client secrets, code_verifier values, API keys, or the bearer token Bilt sends you, or your whsk_ signing key. You can log partnerUserId, your partner ID, and requestId. Keep personal data out of partnerUserId and your logs.

​
Data Bilt stores

Bilt stores only opaque IDs, states, and timestamps, in an append-only audit trail encrypted at rest. Bilt stores every order event as you sent it.

​
Account deletion

When a customer deletes their account with you, end the link. Automated cleanup when a Bilt account is deleted is planned but not in place, so do not rely on it.