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.

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 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 below).
3. Click Create. The dialog displays the Client ID and Client Secret exactly once — copy both into a secret store before closing.

2. Exchange credentials for an access token

Send a POST to the token endpoint with an application/x-www-form-urlencoded body:

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'

A successful response is a standard OAuth 2.0 token:

{
  "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:

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 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, 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 <jwt> 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. The flows below remain documented for organizations still operating existing API Clients.

Create API Client With API Key

1. Visit the settings page 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.

   

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,

  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

1. Visit the settings page 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.

   

Get / Refresh Bearer Token

Send a POST request to https://api.suger.cloud/public/apiClient/accessToken following the API Auth Reference.

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.

{
  "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,

  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

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 <token> 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 for more granular control.