Security

The Cloudpath REST v2 APIs use Json Web Tokens (JWT) to secure all endpoints, in addition to using the API key.
Note: Root URIs and the generation of tokens is somewhat different for tenant portal APIs. If you are using tenant portal APIs, be sure to see Tenant Portal API Requirements.
added this for 5.8

The user calls "..../admin/apiv2/APIKey/token", with a user name and password, and, if authenticated, a JWT token is returned to the user in the authentication response body.

Note: You must include an active JWT token in the "Authorization" HTTP request header of all subsequent requests.

The token has a five-minute timeout and can be refreshed by requesting a new token while the current token is still valid. In addition, the "..../admin/apiv2/APIKey/token" endpoint provides basic information about the token's expiration.

Note: If you change the API key in the Cloudpath UI, all tokens become invalid, and new authentications are required. In addition, if you disable the API key, all API requests are rejected, even if the token is still valid and the user has already been authenticated.

The following table lists the properties that can be used in the body of a token request and/or are provided in the response body.

Resource: Token

Property Name Type Editable Filter or Sort Optional Description
userName String Yes Neither Required only on a PUT call request, but always returned in the response to a PUT or a POST. The username of the person trying to use the API. The user needs to have the account admin role for the account being requested.
password String Yes Neither Required only for a POST request. The password for the user. Will never be returned in the response body.
Note: Not required for obtaining a token for the tenant portal APIs. Refer to Tenant Portal API Requirements.
added this for 5.8
token String No Neither Yes (Never needed in request body) The token returned for this user. Will be ignored on a POST and a PUT.
expireDateTime String < DateTime> No Neither Yes (Never needed in request body)
correct
Expiration time and date for the token returned to the user, given in iso80601 date/time format.

Security URIs and Actions

The following table indicates the URIs that you can append to the root URI, along with the actions you can take, and possible return codes you can receive.

Security URIs and Actions

URI Action Description Return Codes
/token POST Authenticates the user and returns a valid security token. The body must include the username and password.

401 - Unauthorized

201 - Created

PUT Provides an updated token, without requiring a new login. The body must be empty and the current valid token must be in the "Authorization" header.

422 - Entity cannot be processed (if the body is not empty).

406 - Not Acceptable (token has expired)

401 - Unauthorized

Example of Generating an Authorization Token

Note: Root URIs and the generation of tokens is somewhat different for tenant portal APIs. If you are using tenant portal APIs, be sure to see Tenant Portal API Requirements.
added this for 5.8

URI:

This example uses the following URI: 

 https://Jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/token

where:

  • https://Jeff245.cloudpath.net/admin/apiv2 is the root URI of the Cloudpath system being used (must include https, as shown)
  • yRCjJObWR6ER is an example of an API key generated from the Configuration > API Keys section of the Cloudpath UI

Request Headers:

The following table shows the required request header for this URI example:

Request Header

Key Value
Content-type application/json

Request Body:

An example of the request body is shown below (this provides administrative login credentials to the Cloudpath system being used): 

{"userName":"jeffr@commscope.com",
"password":"test"}

Action:

Use the POST action to send the request.

Response Body:

Once the request is sent, you will receive the response body that provides the token and its expiration, as shown in the following example: 

{
    "userName": "jeffr@commscope.com",
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqZWZmLnJob2RpZUBhcnJpcy5jb20iLCJyb2xlUGsiOiIyMTAwMCIsImFjY291bnRBZG1pblBrIjoiMiIsImFwaUtleSI6IkhOV2dNSG93cERCNCIsImlhdCI6MTU3NTQ4NjExMSwiZXhwIjoxNTc1NDg2NDExfQ.JwBWDgj_K7jP1kDvVU8aq_vmNulsdx2FD_MUNLAuymQ",
    "expireDateTime": "2019-12-04T12:06:51-07:00[America/Denver]"
}

Note: Because each token expires after five minutes, you will need to re-send the request often. You need to use the active token with all other requests, as shown elsewhere in this document.
Parent topic: Cloudpath REST API Basics