API Reference

The Suger API for cloud marketplace automation.

Build integrations that automate the full marketplace lifecycle — listings, private offers, agreements, metering, and revenue reporting — from a single REST API.

View API Reference Get API credentials

api.suger.cloud

GET /org/{orgId}/offer

POST /org/{orgId}/offer

GET /org/{orgId}/entitlement

POST /org/{orgId}/usage/meter

GET /org/{orgId}/report

Built for production

Access every marketplace workflow programmatically

Create offers, manage agreements, submit usage data, and generate reports — all through consistent REST endpoints.

Production-grade

Built on the infrastructure behind Suger's 99.9% platform uptime

Two auth methods

An API key for server-to-server calls, OAuth 2.0 for MCP and interactive clients

RESTful design

Consistent, predictable, org-scoped patterns across all endpoints

Stable contract

Existing endpoints do not break; a breaking change would ship as a new host with 12 months notice

Quick start

Make your first API call in seconds

cURL

# Option 1 — API key (server-to-server)
curl -X GET "https://api.suger.cloud/org/YOUR_ORG_ID/offer" \
  -H "Authorization: Key YOUR_API_KEY"

# Option 2 — OAuth 2.0, for MCP clients and interactive apps
# a. exchange client credentials for an access token
curl -X POST "https://apiv2.suger.cloud/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "resource=https://api.suger.cloud"

# b. call the API with the returned bearer token
curl -X GET "https://api.suger.cloud/org/YOUR_ORG_ID/offer" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Hosts and versions

Which host to call

Suger uses two hosts: one issues tokens, the other serves the API. apiv2.suger.cloud is not a second version of the REST API — it is the OAuth authorization server and MCP host. The REST API has no version segment in its paths.

Resource host	`https://api.suger.cloud` Every documented endpoint. Paths are org-scoped: `/org/{orgId}/…`
Token host	`https://apiv2.suger.cloud/oauth2/token` OAuth 2.0 only. Request `resource=https://api.suger.cloud`
MCP endpoint	`https://apiv2.suger.cloud/mcp` See the Suger MCP server
API version	`1.0` Declared in the OpenAPI document. There is no `/v1` or `/v2` path segment, and no v2 REST API.
API key	`Authorization: Key <apiKey>` Server-to-server integrations. Manage keys under API clients in your organization settings.
OAuth 2.0	`Authorization: Bearer <accessToken>` MCP clients and interactive apps. Tokens are issued by the authorization server and scoped to the resource host.

Versioning and deprecation

New fields and new endpoints ship without prior notice.
Existing endpoints do not receive breaking changes.
A breaking change ships as a new versioned host, announced at least 12 months before any sunset, with a migration guide.
Deprecated endpoints return a Sunset header for the duration of the notice period.

OAuth grants supported: client_credentials, refresh_token, authorization_code (with PKCE). Discovery metadata is served from https://apiv2.suger.cloud at /.well-known/openid-configuration, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, /.well-known/jwks.json.

FAQ

API questions, answered

What is the Suger API? +

The Suger API is a REST API for automating cloud marketplace operations — creating private offers, managing agreements, submitting metering records, and generating reports across AWS, Azure, GCP, and Snowflake marketplaces.

How do I authenticate with the Suger API? +

Two methods are supported. For server-to-server calls, create an API client in your organization settings and send `Authorization: Key <apiKey>` — this is the method the OpenAPI document declares. For MCP clients and interactive apps, use OAuth 2.0: exchange your client ID and secret at https://apiv2.suger.cloud/oauth2/token with resource=https://api.suger.cloud, then send `Authorization: Bearer <accessToken>`.

What is the API base URL? +

The REST API is served from https://api.suger.cloud. Endpoints are scoped to your organization under /org/{orgId}/… — for example, https://api.suger.cloud/org/{orgId}/offer. Tokens come from a separate host, https://apiv2.suger.cloud. Despite the name, apiv2.suger.cloud is not a second version of the REST API: it is the OAuth authorization server and MCP host.

Are there rate limits? +

Yes. Rate limits are applied per organization to keep the API reliable for everyone. Specific limits are not published because they vary by plan and endpoint — check your current quotas in the Suger console, or contact support@suger.io if you expect high request volumes.

Does Suger offer SDKs? +

Yes. Official SDKs are available for Node.js, Python, Go, and Java. See the SDKs page for installation instructions and code samples.

Are webhooks supported? +

Yes. Suger sends webhooks for offer acceptance, agreement updates, and disbursement events. Every payload is HMAC-signed with your webhook secret and carries an X-Suger-Signature-256 header you can verify before trusting the request.

Ready to build with Suger?

Create your OAuth credentials and start automating your cloud marketplace workflow today.

View Full API Docs Get API Credentials