OAuth Apps: API Access for Integrations | Cloudmon

OAuth Apps

Integrations

OAuth Apps

Register external applications and scripts to access Cloudmon APIs with OAuth 2.0 client credentials securely.

Overview

OAuth Apps let external applications and scripts, such as a CMDB, ITSM, or reporting tool, access Cloudmon APIs securely.

An app does not need a Cloudmon user account, a password, or an active login session. It has its own role and access scope, and it can be disabled, have its secret rotated, or be deleted at any time without affecting any user.
OAuth Apps: how an integration connects
STEP 1
Register app
A Super Admin registers the app and receives a Client ID and Client secret
STEP 2
Get token
The integration exchanges them at the Token URL for an access token
STEP 3
Call APIs
Each API call sends Authorization: Bearer with the token
STEP 4
Renew
At 15 minutes, or on a 401, the integration requests a new token

Step 1: Registering an App

  1. Navigate to Settings → General Settings → Integrations.
  2. In the API Access section, find the OAuth Apps card and click + App. The Register App form opens.
    SectionDescription
    Setup GuideA reference panel for the integration team. 
    Enable AppOn by default. When it is off, the app can't get or use tokens.
    DetailsName (required): a name that identifies the integration, such as ServiceNow CMDB.
    Description: an optional note on what the integration does.
    PermissionsRole (required): the app gets exactly this role's permissions. 
    Access ScopeLimits the customers and groups the app can see.
    Customers: All Customers, or Select Customers to choose one or more. Available in the MSP edition.
    Groups: All Groups, or Select Groups to choose one or more.
  3. Fill in the sections as described in the above table. Name and Role are required.
  4. Click Register.
  5. In the App Credentials dialog, copy the Client ID and Client secret with their copy buttons and store them securely, for example in a secrets vault. The dialog also shows the Token URL.
  6. Select I have copied the client secret, then close the dialog.
  7. Give the Client ID, Client secret, and Token URL to the team building the integration.
CredentialDescription
Client IDStarts with cmc_. Identifies the integration. It stays the same until the app is deleted.
Client secretStarts with cms_. The password of the integration. It is shown only once and stays valid until it is rotated.
Access tokenStarts with cma_. Sent with every API call. It is valid for 15 minutes.
The Client secret is shown only once, right after registering, and can't be retrieved later. If it is lost, use Rotate secret to issue a new one.

Step 2: Get an Access Token

In the examples in this article, replace <cloudmon-address> with your Cloudmon address, and CLIENT_ID and CLIENT_SECRET with your credentials.

Send a POST request to the Token URL with grant_type=client_credentials.

curl -s -u "CLIENT_ID:CLIENT_SECRET" \
-d "grant_type=client_credentials" \
https://<cloudmon-address>/api/oauth/token

A successful response looks like this:

{ "access_token": "cma_...", "token_type": "Bearer", "expires_in": 900 }

Send the credentials as HTTP Basic authentication, as in the example, which is recommended, or as the form fields client_id and client_secret. Don't send both.

Step 3: Call the API

Send the access token in the Authorization header of each call.

curl -s -H "Authorization: Bearer ACCESS_TOKEN" \
"https://<cloudmon-address>/api/<your-api>"

Every API that the app's role allows works the same way.

Step 4: Renew the Token

An access token is valid for 15 minutes, the expires_in value. To renew it, repeat Step 1 with the same Client ID and Client secret.

  • Recommended: renew about a minute before expires_in runs out, so that a call never fails in the middle of a job.
  • Fallback: if a call returns 401 with the header WWW-Authenticate: Bearer error="invalid_token", request a new token and retry the call once.

Managing OAuth Apps

Click the app count on the OAuth Apps card to open the OAuth Apps Integration window. It lists every registered app with its status, and its Add button opens the Register App form. Use the action icons on an app's row as described in the following table.

ActionDescription
Copy Client IDCopies the app's Client ID.
EditOpens the app to change its name, description, role, access scope, or status. Changing only the name or description has no effect on the integration. Changing the role, access scope, or status cancels all of the app's tokens, and the integration must request a new token.
Rotate secretIssues a new Client secret, shown once. The old secret and all of the app's tokens stop working immediately. Use it if the secret may have leaked, or as routine hygiene.
Revoke tokensCancels all of the app's current tokens. The same Client ID and Client secret can request new ones. Use it if a token may have leaked.
DeleteRemoves the app and all its tokens permanently. To confirm, type the app's name. Use it when the integration is retired.

To pause an integration temporarily, edit the app and switch Enable App off. Switch it on again to let the integration request tokens.

Security Best Practices

  • Treat the Client secret like a password. Keep it in a secrets manager or an environment variable, never in source code, tickets, or chat.
  • Use one app per integration. Each app has its own audit trail and can be revoked without affecting the others.
  • Give the least privilege. Use a read-only role, and limit customers and groups where possible. Avoid the Super Admin role.
  • Rotate the secret regularly, and immediately if it may have been exposed.
  • Use HTTPS for all calls.