Call groups
Calls are categorized by both access requirements and functions. This is done to route requests of similar behavior through a chain of message handlers designed specifically to implement that behavior.
Each request is essentially routed through handlers that are designed to verify a specific aspect of the request before allowing it to continue. Once the request is processed, the response is routed back through those handlers before being transmitted to the client. Each call has a unique call process.
Public calls
The Public requests group represents the minimum required processing, reserved for unauthenticated, low security requests which are informative only. This is also the "base route", meaning that every handler route is built on these minimum requirements. Every request will be, at minimum, SSL verified and logged (if logging is enabled).
-
The SSL Authentication Handler verifies that, if SSL is enabled, HTTPS is being used. If this is not the case, a HTTP 403 error stating "Forbidden" is returned.
-
If Detailed Logging is enabled, the Log Handler logs the details of the inbound request, as well as the outbound response to the client.
Authorization (OAuth2) calls
The oauth2 group supports only two requests, token and revoke. The token request returns a token pair, access_token and refresh_token, based on either a user's credentials, or a previously assigned refresh_token. The revoke token sends a request to terminate a valid access_token and its corresponding user session.
-
Basic Authentication Handler: All oauth2 requests require an encoded ClientID, which is verified by the Basic Authentication handler. The ClientID value is decoded and compared against its defined value stored in the Platform Security Settings. The Basic Authentication handler returns an HTTP 401 (Unauthorized Request) if authorization fails.
-
OAuth Handler: This handler constructs the parameters based on the specific request for appropriate processing. Token request by credentials will have the userid and password verified by the Advanced Inventory system, whereas a refresh_token based request will be checked against the refresh_tokens assigned to existing tokens.
API calls
The remaining requests constitute the groups Device, Messages, Function, SQL, DeviceDBSync, and Notification. These requests require the HTTP headers for deviceid and access_token.
Beginning in 9.0 SP10, the DevStudio group can be used by developers to perform Application Studio functions without the user interface. Requests in the DevStudio group require an access_token, but do not require a deviceid.
Other input parameters may be required, depending on the request. However, those requirements are checked per request, not globally via the handlers assigned to this route.
-
Credential handler: The credential handler has the following responsibilities.
-
Verify that the deviceid and access_token headers exist, and that deviceid header actually contains a value (unless it's a “GetUniqueDeviceId” request where the value is inconsequential).
-
Determine if the provided access token is still valid. The Inactive timeout or “time to live” (TTL) configured values might have been exceeded, in which case the access token has expired.
-
Verify that the Device ID is assigned to the user associated with the given access_token, and if not, whether the check should be skipped due to the request type (aka “device group specific requests”). For example, if the user requests “RegisterDeviceID”, then the Device ID being passed in represents a new value to be registered and there is no reason to verify that it exists.
-
-
Role handler: The role handler validates that the user associated with this access token has the authority to execute the attempted request. Access to individual API functions/requests can be controlled by custom roles defined by the customer, so validation is done for every request.
-
Access token handler: The access token handler is responsible for flood control. Only one processing request is allowed per access token. This prevents attempts at exploiting a single access token by multiple clients.
Loading...
There was a problem loading this topic