Suger

OAuth App

Access the Suger API using the OAuth 2.0 client-credentials flow.

Overview

An OAuth App is a machine-to-machine credential for the Suger API. It is the recommended replacement for the legacy API Client (API_KEY / BEARER_TOKEN), and follows the standard OAuth 2.0 client_credentials grant (RFC 6749 §4.4).

Use an OAuth App 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://auth.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'

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.

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.