# API Access Access the Suger API using the OAuth 2.0 client-credentials flow (recommended) or the legacy API Client. --- ## Overview To call the Suger API from a backend service, script, or integration, you need a machine-to-machine credential for your organization. Suger supports two mechanisms: - **OAuth App** (recommended) — a credential that follows the standard OAuth 2.0 **client_credentials** grant (RFC 6749 §4.4). - **API Client** (legacy) — the older `API_KEY` / `BEARER_TOKEN` mechanism. :::warning **API_KEY and BEARER_TOKEN are deprecated.** New integrations should use an [OAuth App](#oauth-app-recommended). The legacy API Client flows below remain documented for organizations still operating existing API Clients. ::: :::info - OAuth tokens are short-lived (1 hour). Your client should exchange the credentials for a new token when the previous one expires or is about to. - The `client_secret` (OAuth) and the `API Key` / `Client Secret` (API Client) are shown **only once** at creation and at every rotation. Store them somewhere safe (a secret manager, not source control). ::: ## Hosts and authentication | Surface | Host | Authentication | | --- | --- | --- | | REST API (resources) | `https://api.suger.cloud` | `Authorization: Bearer ` from an OAuth App, or the legacy API Client header | | OAuth token endpoint | `https://apiv2.suger.cloud/oauth2/token` | `client_id` + `client_secret`, `grant_type=client_credentials`, `resource=https://api.suger.cloud` | | MCP server | `https://apiv2.suger.cloud/mcp` | OAuth — see [MCP](/mcp/) | | Console | `https://console.suger.io` | Browser sign-in | :::warning **The token endpoint and the resource API are on different hosts.** Request the token from `apiv2.suger.cloud`, then call `api.suger.cloud` with it. The `resource` parameter names the API the token is for. ::: Endpoint paths carry no version prefix — they start at `/org/{orgId}/…`, and the published OpenAPI document reports version `1.0`. For request limits, see [Service quotas](/get-started/quota/). Hosts and authentication verified against the published OpenAPI specification on 2026-08-05. ## OAuth App (recommended) An **OAuth App** is the recommended replacement for the legacy API Client. Use it when a backend service, script, or integration needs to call the Suger API on behalf of your organization. ### Prerequisites - A Suger organization on any pricing plan. - Owner/Admin role on the organization (required to create OAuth Apps). ### 1. Create an OAuth App 1. Go to the [organization settings](https://console.suger.io/settings) and open the **API Client** tab. Scroll down to the **OAuth Apps** section. 2. Click **+ New OAuth App**. Fill in: - **Name** — a label, e.g. `Billing sync (prod)` - **Description** — optional free-text - **Access Level** — select `VIEWER`, `EDITOR`, or any custom role defined in your organization. This role determines what the access token is allowed to do (see [Permissions](#permissions) below). 3. Click **Create**. The dialog displays the **Client ID** and **Client Secret** exactly once — copy both into a secret store before closing. :::warning The Client Secret cannot be recovered. If you lose it, use **Rotate Secret** to generate a new one (which invalidates the previous secret immediately). ::: ### 2. Exchange credentials for an access token Send a `POST` to the token endpoint with an `application/x-www-form-urlencoded` body: ```shell curl -L -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' ``` :::info The `resource=https://api.suger.cloud` parameter is **required**. It tells the authorization server to issue a JWT access token scoped (`aud`) to the Suger API. Without it, the server returns an opaque token that the API will reject. ::: A successful response is a standard OAuth 2.0 token: ```json { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...", "token_type": "Bearer", "expires_in": 3600 } ``` The access token is an RS256-signed JWT. Tokens expire in **1 hour**. Cache the token in memory for the duration of `expires_in` and request a new one when it expires. Do not request a new token on every API call. ### 3. Call the Suger API Include the access token in the `Authorization` header of every API request: ```shell curl -L -X GET 'https://api.suger.cloud/org/YOUR_ORG_ID/user' \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...' \ -H 'Content-Type: application/json' ``` Replace `YOUR_ORG_ID` with the Suger organization ID. Refer to the [API Reference](https://doc.suger.io/api) for the full list of endpoints. ### Permissions What an access token can do is governed by the **role** assigned to the OAuth App at creation — not by OAuth scopes. - **VIEWER** — read-only access to the organization's resources. - **EDITOR** — read and write access to the organization's resources. - **Custom roles** — if your organization has defined custom roles under [Users & Roles](https://console.suger.io/settings), you can assign one of those instead for fine-grained permissions. To change the permissions of an existing OAuth App, delete it and create a new one with the desired role. ### Rotate or delete an OAuth App - **Rotate Secret** — On the OAuth Apps row, click the rotate icon. Suger generates a new `client_secret` and displays it once. The previous secret is invalidated immediately, so deploy the new secret before rotating. - **Delete** — Click the trash icon. The OAuth App is removed and access tokens issued for it stop working. ### Migration from the legacy API Client If you currently authenticate with `Authorization: Key …` (API_KEY) or `Authorization: Bearer …` from the legacy `/public/apiClient/accessToken` endpoint, switch to an OAuth App at your earliest convenience. The `Authorization: Bearer ` header used by an OAuth App access token is wire-compatible with the legacy bearer flow — your API calls do not change, only the way you obtain the token. ## API Client (legacy) The API Client is the legacy authentication mechanism. `API_KEY` and `BEARER_TOKEN` are deprecated; new integrations should use an [OAuth App](#oauth-app-recommended). The flows below remain documented for organizations still operating existing API Clients. :::warning - Each organization can create up to **FIVE** API Clients. - If your organization needs additional API Clients with specific justifications, please contact our support team at support@suger.io. We are available to help you manually add extra API Clients to your organization ::: ### Create API Client With API Key 1. Visit the [settings page](https://console.suger.io/settings) of your organization. Find the `API Client` section as shown below. 2. Click the button `CREATE API CLIENT` and select `API_KEY` as the Auth Type. Please store the `API Key` carefully in a safe place, since it only shows once. > Create API Client dialog with API Key auth type #### Use API Key to Access Suger API - In order to access the suger API, you should include the `API Key` in the HTTP request header under the `Authorization` field, with the format `Key ...`. For example, ```shell curl -L -X GET 'https://api.suger.cloud/org/sugerOrgId/user' \ -H 'Content-Type: application/json' \ -H 'Authorization: Key 673d5b018d472f...' ``` ### Create API Client With Bearer Token :::danger - Creating a new API client with bearer token is no longer supported. Instead, please create a new API client with API key. - Existing API clients that use a bearer token can still be utilized to access the Suger API without any disruption. ::: 1. Visit the [settings page](https://console.suger.io/settings) of your organization. Find the `API Client` section as shown below. 2. Click the button `CREATE API CLIENT` and select `BEARER_TOKEN` as the Auth Type. Please store the `Client Secret` carefully in a safe place, since it only shows once. > Create API Client dialog with Bearer Token auth type #### Get / Refresh Bearer Token Send a `POST` request to `https://api.suger.cloud/public/apiClient/accessToken` following the [API Auth Reference](#2-exchange-credentials-for-an-access-token). ```shell curl -L -X POST 'https://api.suger.cloud/public/apiClient/accessToken' \ -H 'Content-Type: application/json' \ -d '{ "organizationID": "your-suger-organization-id", "id": "your-API-client-id", "secret": "your-API-client-secret" }' ``` If successful, you shall receive a `200 OK` response with payload like below. The default expiration time of the token is `1 hour`. ```json { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6I...", "expires_in": 3600, "expires_on": "2023-05-15T04:41:58.670945Z", "token_type": "Bearer" } ``` #### Use Bearer Token to Access Suger API - In order to access the suger API, you should include a `bearer token` in the HTTP request header under the `Authorization` field, with the format `Bearer ...`. For example, ```shell curl -L -X GET 'https://api.suger.cloud/org/sugerOrgId/user' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6I...' ``` ### Rotate API Client Secret / API Key Suger doesn't save your `Client Secret` or `API Key`. If you forget or lose it, the API client has to be rotated with a new secret or API Key. Click the rotate secret icon to do it. Once the `Client Secret` or `API Key` is rotated, the old one will be invalid immediately. ### Delete API Client Click the delete icon to delete the API client. Then you are available to create a new one. ## Troubleshooting | Issue | Possible cause | Resolution | | --- | --- | --- | | API calls return `401 Unauthorized` | Expired access token | Request a new token from the OAuth token endpoint (or the legacy `/public/apiClient/accessToken`). Cache tokens for their full `expires_in` duration. | | API calls return `401 Unauthorized` | Wrong `Authorization` header format | OAuth App and legacy Bearer Token both use `Authorization: Bearer `. The legacy API Key uses `Authorization: Key `. Confirm the correct format for your auth method. | | Token request returns `400 Bad Request` | Incorrect `Content-Type` or malformed body | OAuth App token requests require `Content-Type: application/x-www-form-urlencoded`. Legacy Bearer Token requests require `Content-Type: application/json`. | | API returns errors even with a valid-looking token | Missing `resource` parameter | Include `resource=https://api.suger.cloud` in the token request so the server issues a JWT scoped to the Suger API. | | Client Secret lost | Secret was not stored at creation | Rotate the credential. The previous secret is invalidated immediately — deploy the new one before rotating to avoid downtime. | | Need to change OAuth App permissions | Permissions are set at creation and cannot be edited | Delete the OAuth App and create a new one with the desired role (`VIEWER`, `EDITOR`, or custom). | ## Frequently asked questions **Should I use an OAuth App or an API Client for a new integration?** Use an OAuth App. `API_KEY` and `BEARER_TOKEN` are deprecated. OAuth Apps follow the standard OAuth 2.0 client-credentials flow and are the supported path for all new integrations. **How long do access tokens last?** Both OAuth App tokens and legacy Bearer Tokens expire after **1 hour** (`expires_in: 3600`). Cache the token in memory and request a new one when it expires. **What happens if I lose my Client Secret?** It cannot be recovered — Suger does not store it. Use **Rotate Secret** in your organization settings. The old credential is invalidated immediately, so have your deployment ready before rotating. **Can I change the permissions on an existing OAuth App?** No. Permissions are set at creation. To change them, delete the existing OAuth App and create a new one with the desired role. **I'm currently using an API Key or Bearer Token. Do I need to migrate immediately?** Not immediately — existing API Clients continue to work. Migrating to an OAuth App is recommended. The `Authorization: Bearer ` header used by OAuth Apps is wire-compatible with the legacy Bearer Token flow, so your API calls don't change — only how you obtain the token. **What is the difference between VIEWER and EDITOR access levels?** VIEWER provides read-only access to your organization's resources. EDITOR provides read and write access. Custom roles can be defined under [Users & Roles](https://console.suger.io/settings) for more granular control.