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}/entitlement/{entitlementId}/usageRecordGroup

POST /org/{orgId}/revenueReport

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

OAuth 2.0 authentication

Client-credentials tokens for server-to-server calls; the legacy API key still works but is deprecated

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

# Recommended — OAuth 2.0 client credentials (server-to-server)
# a. exchange your OAuth App's client ID and secret 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"

# Legacy — API key (deprecated; for existing integrations only)
curl -X GET "https://api.suger.cloud/org/YOUR_ORG_ID/offer" \
  -H "Authorization: Key YOUR_API_KEY"

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.
OAuth 2.0	`Authorization: Bearer <accessToken>` Server-to-server integrations (recommended) and MCP clients. Create an OAuth App in your organization settings; tokens are issued by the authorization server and scoped to the resource host.
API key (legacy)	`Authorization: Key <apiKey>` Existing integrations only — deprecated. Manage keys under API clients in your organization settings.

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? +

Use an OAuth App, the recommended credential for server-to-server calls: create one in your organization settings, exchange its client ID and secret at https://apiv2.suger.cloud/oauth2/token with grant_type=client_credentials and resource=https://api.suger.cloud, then send `Authorization: Bearer <accessToken>`. The legacy API client (`Authorization: Key <apiKey>`) still works but is deprecated.

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