How your integration authenticates with the Topiic API and how Topiic proves webhooks are genuine.
Your integration has one credential pair to manage: an API key for REST calls, and a paired signing secret for hosted-checkout deep links and webhook signatures. That’s it.
API key — your server calling Topiic
Section titled “API key — your server calling Topiic”A long-lived credential scoped to one merchant. Looks like tpk_<32-bytes base64url>. Mint one in the Topiic portal under Settings → API keys; copy it the moment you see it — Topiic only stores a hash and cannot show it to you again.
Send it on every REST call as:
Authorization: Bearer tpk_…API keys can be revoked from the portal at any time. Revocation is immediate — in-flight requests may complete, subsequent ones get 401 Unauthorized.
Signing secret — for deep links and webhook verification
Section titled “Signing secret — for deep links and webhook verification”Each API key comes with a paired signing secret (tss_<32-bytes base64url>). It’s the HMAC key for:
- Building hosted-checkout deep links on your server.
- Verifying webhook signatures on inbound POSTs from Topiic.
You see the plaintext signing secret exactly once at creation time — copy it into your secret manager along with the API key. Both credentials are equally sensitive.
Quick reference
Section titled “Quick reference”| Credential | Looks like | Where it goes | Lifetime |
|---|---|---|---|
| API key | tpk_… | Authorization: Bearer … header on REST calls | Until you revoke or it expires |
| Signing secret | tss_… | HMAC-SHA256 input for deep links + webhook verification | Until the API key is revoked |
Why deep links use a signature, not the API key
Section titled “Why deep links use a signature, not the API key”Deep links sit in browser URLs where anyone can copy them. If we authenticated them with the API key directly, anyone with a link could call any REST endpoint on your behalf.
Instead the link carries an HMAC over a structured payload — Topiic can verify “this was issued by the holder of the signing secret” without the secret ever traversing the wire. The signed link is also single-use (per-nonce) and time-bound (per exp), so even a copied link cannot be replayed.