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.

TypeAPI key
HeaderX-SureBright-Access-Token
Key formatsb_live_ followed by a random secret. This is the only prefix; see Live keys and testing

🔒 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):

  1. 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.

  2. 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.

  3. 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.

You want toWhat to do
Check your ids and see real responses without writing dataCall the category and quote endpoints. They need no key. The API playground on the Developers page runs them against your store.
Try the Order endpoints without recording a real saleSend "isTestOrder": true in the order body. The order is recorded as a test order and its rows carry a Test badge on Sales.
Work against a staging environmentStaging and production use different hosts and different keys. Ask your SureBright contact for the staging host and credentials.

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#

bash
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#

StatusBodyCause
401{"message": "Unauthorized! x-surebright-access-token header is required."}Header missing
401{"message": "Unauthorized! Invalid or revoked API key."}Key unknown, or revoked / rotated
401{"message": "Unauthorized! Invalid token."}Integration-kit token not recognised
401{"message": "Unauthorized! Invalid or expired token.", "error": "..."}Integration-kit token malformed or expired

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 Kit

  • X-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 is api.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.