Security

The Cloudpath REST APIs use Json Web Tokens (JWT) to secure all endpoints.
updated for 5.9

The user calls "..../admin/publicApi/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/publicApi/token" endpoint provides basic information about the token's expiration.

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.
serverVersion String No Neither Yes The server version.

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:

updated the following URI for 5.9

 https://Jeff245.cloudpath.net/admin/publicApi/token

where https://Jeff245.cloudpath.net/admin/publicApi is the root URI of the Cloudpath system being used (must include https, as shown).

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 an active token with all other requests.
Parent topic: Cloudpath REST API Basics