Authentication

The API uses the same accounts and permissions as the rest of Cloud Management Platform (CMP): the roles and group permissions that apply in the web interface also apply to the API.

Prerequisites

An account you can log in to the web interface with. Every user has API access.

Get a bearer token

With curl

Replace cmp-ip-or-hostname, username, and password. Include domain only when logging in against a directory domain.

curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"username":"<username>","password":"<password>","domain":"<domain>"}' \
  "https://<cmp-ip-or-hostname>/api/v3/cmp/apiToken/"

The response contains token, the short-lived access token you send with each request, and refreshToken, the longer-lived one you exchange for a new access token.

{
  "token": "<access-token>",
  "refreshToken": "<refresh-token>"
}

With the API console

1. Go to /api/v3/cmp/apiToken/ on your CMP address, for example 10.11.12.13/api/v3/cmp/apiToken/.

2. In the POST Data content field, supply your username and password, and domain if you use one:

   {
     "username": "{{username}}",
     "password": "{{password}}",
     "domain": "{{domain}}"
   }
   

3. Select POST.

Pass the token with each request

Send the access token in the Authorization header:

Authorization: Bearer {{access_token}}

Refresh an expired token

Access tokens are short-lived. Exchange the refresh token for a new access token by posting it to /api/v3/cmp/apiTokenRefresh/. The refresh token goes in a field named token:

{
  "token": "<refresh-token>"
}

The response returns the new access token, again as token:

{
  "token": "<new-access-token>"
}

Once the refresh token expires, request a new pair with your credentials.

Token lifetimes

A token pair has two components, each with its own default lifetime.

Change the token lifetimes

1. Define the SIMPLE_JWT dictionary in /var/opt/cloudbolt/proserv/customer_settings.py. It replaces the built-in one, so include both keys:

   from datetime import timedelta
   
   SIMPLE_JWT = {
       "ACCESS_TOKEN_LIFETIME": timedelta(hours=24),
       "REFRESH_TOKEN_LIFETIME": timedelta(days=7),
   }
   

   You can use any timedelta unit, including seconds, minutes, hours, and days.

2. Restart the web server to apply the change: systemctl restart httpd.

Tokens issued after the restart carry the new lifetimes. Tokens issued before it keep the old ones until expiry.

Personal access tokens

A personal access token is an alternative to a bearer token and is useful when single sign-on means your users have no password to exchange for one. It is a long-lived token you generate from your user profile and send in the same header, with the Token scheme rather than Bearer:

Authorization: Token <personal-access-token>

CMP endpoints accept either scheme. See Authentication using personal access tokens for how to create, regenerate, and expire one.

Authentication errors

Two status codes are specific to authentication:

• 401: the token is missing, malformed, or expired. Obtain or refresh a token and retry.
• 403: the token is valid, but the account does not have access. Check the user’s permissions.

For the error body shared across all endpoints, see Errors in API conventions.

Extend the API

You can add your own endpoints to the CMP API with a plugin, using an inbound webhook. See Inbound webhooks.