How it works
This page describes the credential foundation: how a brand authorises BBG Sentinel, how that authorisation is stored, and how a system gets permission to use it. It is the layer everything else runs on, and it is the part that is built and in use today.
For what BBG Sentinel is being built to do with that access — the monitoring agents and what each is meant to catch — see the overview.
BBG Sentinel sits between the brands that own Amazon Selling Partner API (SP-API) authorisations and the internal systems that need to call SP-API on their behalf. This is what actually happens, step by step.
1. A brand authorises BBG Sentinel
An administrator of the brand’s Amazon Seller Central or Vendor Central account starts the SP-API authorisation flow and grants BBG Sentinel access to a selected set of roles. Amazon returns a refresh token that represents that grant.
The brand controls this step, chooses which roles are granted, and can withdraw the grant at any time from within Amazon’s own console.
2. The credential is encrypted and stored
BBG Sentinel encrypts the refresh token with Fernet symmetric encryption before it is written to the database. The encryption key lives in Google Secret Manager; the application reads it at runtime through its service account and never stores it alongside the data it protects.
The stored record is tagged with the organisation that owns it. From this point on, every read of that record is scoped to that organisation.
3. An internal system asks for an access token
When an internal system needs to call SP-API, it asks BBG Sentinel for an access token for a specific brand and marketplace. It authenticates as itself, by presenting a Google-issued identity token rather than a shared secret. BBG Sentinel validates that token and checks the identity against an allow-list of permitted service accounts; anything not on the list is refused.
Being on the network is not enough to get a token.
4. BBG Sentinel exchanges the credential
This is the only step in BBG Sentinel that decrypts a stored refresh token, and there is exactly one code path that does it. The decrypted value goes straight into the exchange with Amazon’s Login with Amazon endpoint: it is never held in a long-lived variable, never returned to the calling system, never logged, and never copied anywhere else.
What comes back from Amazon is a short-lived access token, and that is what the caller receives. The refresh token itself does not leave the service.
Before the response is returned, the request is written to the append-only audit log: which identity asked, for which organisation, when, and whether it succeeded.
5. The caller uses the token and discards it
The calling system uses the access token directly against SP-API for the duration of its work. The token is short-lived by Amazon’s design; when it expires the caller asks again. Nothing long-lived is persisted outside BBG Sentinel.
6. Withdrawal and revocation
If a brand withdraws its authorisation in Amazon’s console, the refresh token stops working immediately and BBG Sentinel can no longer issue tokens for that account. Revoking an authorisation inside BBG Sentinel marks it as revoked and has the same effect: token issuance from that credential stops.
The encrypted credential is then kept, not deleted. That is deliberate: it remains part of the security record of what existed while the authorisation was active. It is unusable for token issuance, and automated hard-deletion of revoked credentials is planned but not yet implemented — until it is, removing one from storage is a manual operation we perform on request.
The audit log of past issuances is likewise retained. It is a record of what happened, not a copy of the credential. The Privacy policy sets out both in full.
Where it runs
BBG Sentinel runs on Google Cloud in the European Union, region europe-west4 — both the application and its database. It uses a managed database configured to accept encrypted connections only, Secret Manager for key material, and least-privilege runtime service accounts separated per component. Database access uses short-lived IAM tokens rather than a static password.
This website is a separate, static site. It contains no credentials, calls no Amazon endpoint, and is deliberately kept independent of the platform it describes.
Questions
The Privacy policy sets out in detail what data is held and for how long. For anything else, contact us.