Connecting Suger¶
Suger is the aggregator that holds your AWS, Azure and GCP listings and reports one entitlement shape to Omnistrate. Connecting it is a one-time setup in FinOps Center → Marketplace Channels.
Before You Start¶
You need three things from Suger, and one thing from your own product:
- A Suger organization with your listing in it.
- An OAuth app created under Suger's organization settings. Suger deprecated API key authentication; Omnistrate now exchanges a client id and secret for a one-hour bearer token on every call.
- The webhook signing secret Suger shows you, so Omnistrate can verify inbound webhooks from it.
- A callback URL on your own portal, where buyers land after onboarding.
Register the Landing URL First¶
Open the Suger card and the drawer shows your Omnistrate landing URL before it asks for anything else. That is deliberate: this URL has to be registered in Suger before a purchase can reach you, and you can copy it before you have credentials.
Register it in Suger, the product configuration, in the field named Signup URL.
Register with the aggregator, not the cloud marketplace
The cloud marketplace listing should point at Suger. The Omnistrate landing URL goes into Suger. An ISV who registers it directly with AWS sends every buyer to an address that never resolves, and the failure surfaces on the marketplace's side during a real purchase, where nothing in Omnistrate is even called.
The fields¶
Billing provider¶
Read-only, and locked to Suger. Contracts on this channel are billed by the channel, and usage is reported with the same credential. A channel and the provider that collects for it are not independently choosable, so this is shown rather than asked.
Organization ID¶
The Suger organization that holds your listings. Format org_123456.
OAuth client ID¶
From Suger organization settings → API Client → OAuth Apps. Shown once when the app is created.
This is not a password field, on purpose. It is an identifier that authorizes nothing on its own, and you need to read it back to compare against the OAuth app in Suger's console — which is exactly what you will be doing if a grant is ever refused.
OAuth client secret¶
The other half of the OAuth app. Encrypted on arrival and never shown again, so keep a copy.
Omnistrate exchanges the client id and secret for a bearer token valid for one hour, and caches it per ISV. Two ISVs never share a token.
Webhook signing secret¶
Verifies inbound webhooks from Suger to Omnistrate. Contract reads work without it; webhooks are refused until it is set.
Three different secrets
This is the one most easily confused. The webhook signing secret verifies what Suger sends Omnistrate. The signing secret further down the form is what Omnistrate signs deliveries to you with. The OAuth client secret authenticates Omnistrate to Suger. They are three separate values and none of them substitutes for another.
Where buyers go, and how you are told¶
ISV portal callback URL — required¶
Omnistrate sends the buyer here once onboarding completes, appending ?code= to this URL. Your portal redeems that code server-side to establish the session.
HTTPS only, and no query string of your own — Omnistrate appends one.
This is a user-facing page. A buyer's browser lands on it.
Receiver URL — optional, and it decides the delivery path¶
Leave it empty and the handoff credential arrives on the callback URL above, carried by the buyer's browser. Set it and signed webhooks are delivered here instead, server to server.
Not both. Whichever you configure is the one Omnistrate uses.
This is a program endpoint. It verifies a signature and answers 2xx. Pointing us at your user-facing page here means signed webhooks arrive at a web page; pointing us at your webhook endpoint for the callback sends buyers somewhere they cannot use.
HTTPS only. Private, loopback, link-local and cloud metadata addresses are refused, both at registration and again at delivery time.
A receiver is the only way to hear about changes after the purchase
The redirect happens once, at purchase. A seat change, a plan change, a suspension and a cancellation all happen in the marketplace with nobody visiting your site. If you never register a receiver, you will onboard buyers correctly and never learn that one of them cancelled.
Signing secret¶
What Omnistrate signs deliveries to your receiver with, so you can prove they came from us. At least 32 bytes, because deliveries are signed with HMAC-SHA256 and a key shorter than the hash weakens it.
Write-only: encrypted on arrival and returned by no read, so keep a copy.
Supplying a value is a rotation. Leave it blank when editing anything else on an already-connected channel and the stored secret is kept. There is no way to remove one, because a channel without a signing secret delivers events no conforming receiver accepts.
Map your listings¶
A purchase has to resolve to something you sell. Open Configure listings on the channel card and map each of the channel's plans to one of your SaaS Products and a plan within it.
SaaS Product first, then plan: the plans are read for the SaaS Product once it is chosen, and choosing a different SaaS Product clears the plan. A plan belongs to one SaaS Product, so carrying it across would build a pair that does not exist and the server refuses exactly that pair.
Two rules the mapping enforces:
- The plan must list MARKETPLACE as a billing provider. The channel write refuses a tier that does not, and says so at connect time.
- Only production plans are offered. A marketplace buyer is a paying customer, and serving them from a dev or staging tier would take their money onto a test plan.
A channel cannot be enabled with no mapped listing, because a purchase on a channel that sells nothing resolves to no plan.
Verify the connection¶
The drawer has a Test connection action. It reads back from Suger with the credentials you supplied and reports findings rather than throwing, so a wrong organization id or a refused grant is named before a buyer ever arrives.
What Suger can and cannot do¶
Each channel declares what Omnistrate is allowed to control. Suger owns the registered landing page and the fulfillment callbacks, so the contract is already committed on the marketplace before Omnistrate is called:
| Capability | Suger | What it means |
|---|---|---|
| Can hold contract | No | Omnistrate cannot keep the buyer un-charged while you decide |
| Can report progress | No | No onboarding message can be shown on the marketplace |
| Can cancel | No | Cancellation originates upstream, not from Omnistrate |
| Usage gate | Inherited | Whether usage is gated follows the marketplace's own rule |
This is why the buyer is paying before you confirm, and why fulfillmentState rather than contractStatus is the thing to branch on.