--- title: "Fours API Reference — REST API for Cloud Marketplace" url: https://www.fours.com/resources/apis/ canonical: https://www.fours.com/resources/apis/ type: Resource description: "Automate your cloud marketplace workflow with Fours' REST API. Create offers, manage agreements, submit metering, and generate reports programmatically." --- # Fours API Reference — REST API for Cloud Marketplace > Canonical HTML version: https://www.fours.com/resources/apis/ 1. [Home](/) 2. / 3. [Resources](/resources/) 4. / 5. APIs API Reference # The Fours API for cloud marketplace automation. Build integrations that automate the full marketplace lifecycle — listings, private offers, agreements, metering, and co-sell — from a single REST API. [View API Reference](https://doc.suger.io/api/) [Get API credentials](https://console.suger.io/) api.suger.cloud GET `/org/{orgId}/offer` POST `/org/{orgId}/offer` GET `/org/{orgId}/entitlement` POST `/org/{orgId}/entitlement/{entitlementId}/usageRecordGroup` GET `/org/{orgId}/usageRecordReport` 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 Fours' 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 Fours 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 Fours MCP server](/platform/mcp/) 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 ` 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 ` 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 Fours API? + The Fours 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 Fours 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 \`. The legacy API client (\`Authorization: Key \`) 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? + No. Authenticated API endpoints are not rate limited per request. Usage is bounded by your organization's service quotas instead — view them in the Fours console, and contact support@suger.io to raise one. Does Fours 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. Fours 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 Fours? Create your OAuth credentials and start automating your cloud marketplace workflow today. [View Full API Docs](https://doc.suger.io/api/) [Get API Credentials](https://console.suger.io/)