Authentication
Learn how to authenticate your requests to the SureBright API
Overview#
Only the Order endpoints under /partner/api/v1/order need credentials. They accept a merchant API key in the X-SureBright-Access-Token request header. Set or revert fulfillment dates is separate: it takes its own server-to-server token, described on that page.
Quote endpoints (/quote/api/quote/..., /quote/api/whole-system/listQuotes) and the store category endpoint (/quote/api/storeCategory/listStoreCategories) are public: they take no credentials and do not read X-SureBright-Access-Token. Do not add an Authorization header to these calls; a request that carries one can be answered 401.
🔒 Important:
Your API key grants privileged access—treat it as sensitive information. Never expose your API key in public repositories (e.g., GitHub) or embed it in client-side code.
All API requests must be made over HTTPS. Requests sent over plain HTTP will be rejected.
Getting a key#
Keys are self-serve in the SureBright Merchant Portal, on the Developers page (also linked from the Developers and API card under Settings once the Developer API is enabled on your account):
Create
Enter a label (for example "Production server") and click Generate new key. The full key is shown once, in a one-time reveal dialog with a copy button. After you close it, the portal only ever shows a masked form (
sb_live_abc123••••••••wxyz), so copy it to your secret store first.Rotate
Rotate revokes the existing key immediately and issues a new one with the same label. The new key is shown once, like a freshly created key.
Revoke
Revoke disables a key immediately. Requests made with a revoked key return
401.
A key is scoped to your SureBright account (all stores under the same store parent). Merchants onboarded with a SureBright Integration Kit can keep using the access token issued in that kit; it is accepted in the same header.
Live keys and testing#
Every key created on the Developers page starts with sb_live_. There is no separate development or test key, and no sandbox mode that a key switches on.
A request made with an sb_live_ key reaches your live account. Without isTestOrder, Record an order in the playground and POST /partner/api/v1/order from your server both create real contracts. On a test order, put an email address you control in customerDetails.customerEmail, because order emails can still be sent.
Example Request#
curl -G https://{HOST_NAME}/partner/api/v1/order \
--data-urlencode 'storeId={storeId}' \
--data-urlencode 'partnerOrderId={orderId}' \
-H 'Accept: application/json' \
-H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY'This is the read-only lookup, Get Contracts for Order, so it is safe to run while you check a key. A 401 means the key was not accepted. A 404 with errorCode: ORDER_NOT_FOUND means the key was accepted and there is no such order yet. POST and PUT on the same path take the same header plus Content-Type: application/json.
Send the key, or your Integration Kit token, in X-SureBright-Access-Token only. The Order endpoints do not accept an API key in an Authorization header, so leave that header out. See Request conventions for the rules the Order endpoints share.
Errors#
The whole system warranty endpoints answer a missing header with {"isError": true, "errorType": 401, "message": "X-SureBright-Access-Token header is required"} instead.
Required Credentials#
To call the Order endpoints you need:
storeId– shared as part of the SureBright Integration KitX-SureBright-Access-Token– created on the Merchant Portal Developers page (or issued in the Integration Kit)HOST_NAME– the SureBright API host. The production host isapi.surebright.com, as shown in the curl snippet of the API playground. The staging host is shared by your SureBright contact or in the Integration Kit.