Cloud Inventory® Documentation

Public requests

These are requests that require no authentication or HTTP headers, and are useful for determining whether the Web API service is running.

Example of a ping request: https://{address}:{port}/api/v1/Public/PingUTC

OAuth 2.0 authentication requests

An OAuth 2.0 URL consists of the following POST requests.

Request a new token, either via credentials or a refresh_token.

https://{address}:{port}/oauth2/token
Invalidate an existing token. This replaces the former Logoff request.

https://{address}:{port}/oauth2/revoke

OAuth 2.0 requests use a different URL endpoint than their Web API counterparts, given that the authorization service is treated as a separate entity. The HTTP header requirements for each OAuth 2.0 request type are detailed below. The following sequence diagram illustrates the grant flow interaction.

Client ID

All OAuth 2.0 requests must have an HTTP header labeled “Authorization: Basic” with an encoded ClientID value which matches the Client ID provided in Platform Admin > Configuration > Security Settings on the Web API Agent tab.

This replaces what used to be the access key, and constitutes a shared secret between the Platform and the client. Given that this value needs to be stored on the client for utilization, there is no assumption that it is truly a secret. The purpose is to control client access to the Advanced Inventory system. If you suspect that the ClientID has been compromised, you can change the Client ID in the Platform security settings, which will terminate the connection for any client utilizing the previous ClientID. The newly generated Client ID can then be shared with authorized clients so they can reattach.

Token request using credentials

An access_token request utilizing the “Resource Owner Credentials Grant” requires the following HTTP headers.

Authorization: Set this to Basic and use the encoded ClientID.
grant_type: Set this to password.
Username: Use the Advanced Inventory Login ID.
Password: Use the Advanced Inventory user password.

Example of a successful post and response:

POST https://localhost:8130/oauth2/token
grant_type: password
Authorization: Basic RFNJOg==
username: testUser
password: testPass
Content-Type: application/x-www-form-urlencoded

HTTP/1.1 200 OK
Content-Length: 118
Content-Type: application/json; charset=utf-8
{"access_token":"gZUvJAMfyMDP0eJfF9H/vvnZ1APOuy7RiWLh3RQbUyE=","refresh_token":"063fe8a7-
8472-4f64-b42d-55da55fc4df2"}

Token request using Refresh Token

An access_token request utilizing a refresh_token requires the following HTTP headers.

Authorization: Set this to Basic and use the encoded ClientID.
grant_type: Set this to refresh_token.
refresh_token: Use the Advanced Inventory LoginID.

Example of a successful post and response:

POST https://localhost:8130/oauth2/token
refresh_token: 063fe8a7-8472-4f64-b42d-55da55fc4df2
grant_type: refresh_token
Authorization: Basic RFNJOg==
Content-Type: application/x-www-form-urlencoded


HTTP/1.1 200 OK
Content-Length: 118
Content-Type: application/json; charset=utf-8
{"access_token":"tA0OH3KCCQBYIdoT9H5SoxPyJCkKtb5kaPsUAKLq/p0=","refresh_token":"8737c33c-fc3f-438b-9625-900f1635bb06"}

Revoke request

Invalidating an access_token via a Revoke request requires the following HTTP headers.

Authorization: Set this to Basic and use the encoded ClientID.
access_token: Set this to the access_token to be revoked.

Example of a successful post and response:

POST https://localhost:8130/oauth2/revoke
access_token: tA0OH3KCCQBYIdoT9H5SoxPyJCkKtb5kaPsUAKLq/p0=
Authorization: Basic RFNJOg==
Content-Type: application/x-www-form-urlencoded


HTTP/1.1 200 OK
Content-Length: 0

API Requests

The remaining API requests, which are not part of the Public or oauth2 groups are invoked with the standard format.

https://{address}:{port}/api/{version}/{action}

The required HTTP headers for these requests have been reduced to three with the implementation of the OAuth 2.0 security model. Two of these are required.

deviceid (required)
access_token (required)
inputparams

Device ID

An HTTP header labeled deviceid with a valid alphanumeric device ID value is required. If no Device ID has been assigned for this user, a GetUniqueDeviceId request will generate and return a new one. The user can also assign a Device ID to their session by issuing a RegisterDeviceId request. Regardless of how the Device ID is paired to the user, an error will be returned if the user does not provide their specific Device ID with a request that requires it.

Access token

An HTTP header labeled access_token, with a valid token value, is required. If an access_token is terminated for whatever reason, the client is required to submit an oauth2 token request to receive a new access_token token before they can continue.

While this does not follow the “RESTful” philosophy, it is by design. The API Web Agent maintains a session state of valid access_tokens and users to limit the exposure to spoofing. The lifetime of the access_token will be maintained until the client submits an oauth2 Revoke request, though the lifetime of an access_token can optionally be limited to the following.

A specific duration
A period of inactivity on the user's part

These options are available on the API Web Agent configuration page in the Platform.

Input parameters

The input parameters HTTP header is labeled inputparams. The value will be a JSON formatted string representation of the input structure corresponding to the API call being constructed. The input structure is typically represented as any class or structure, and then serialized to a JSON format after being filled with the values the client requires for the particular call.

Beginning in 9.0 SP11, the input parameters no longer need to be in the same order as the web service. Additionally, you can now use wildcards to call multiple output parameters instead of listing each parameter, using the format OUTPUTPARMNAME.STRUCTURE_OR_TABLE.*. The asterisk calls all parameters under the referenced structure or table.

Mobile Enterprise Platform

Call creation

Public requests

OAuth 2.0 authentication requests

API Requests