WebAPI - How does the OAUTH 2.0 authorization work?

WebAPI - How does the OAUTH 2.0 authorization work?

OAuth 2.0 is a standard authorization protocol that allows applications to access a user's account in a web service (HTTP) such as the Valuekeep CMMS Web API.

The protocol delegates user authentication to the service that holds the user's account and authorizes external applications to access that user's account. The protocol makes authorization flows available for Web, desktop and mobile apps.

We now describe the basic operation of the protocol from the perspective of an application developer.

OAuth Roles

The protocol defines 4 roles:

1.      Resource owner: this is the user who authorizes the application's access to his account. Such access is limited to the scope of the authorization given by the user.

2.      Client: is the application that wants to access the user account.

3.      Resource server: is the server that hosts the user's accounts.

4.      Authorization server: is the server that verifies the identity of the user and assigns authorization tokens to the client (the application).

From the point of view of an application developer, the Web API you want to consume acts both as resource server and the authorization server. It is, therefore, common for the two roles to be combined in what is called a Service or simply an API.

Generic authorization flow

The normal authorization flow from an external application will follow these steps:

1.      The application requests permission to access user resources.

2.      If the user has already authorized such a request, the application receives an authorization grant.

3.      The application asks the authorization server for an access token, showing the user's identity and the authorization grant.

4.      If the application's identity is authenticated and the authorization grant is valid, the authorization server assigns an access token to the application and the authorization flow ends.

5.      The application requests a certain resource from the resource server and displays the access token it obtained before.

6.      If the access token is valid, the resource server will return the requested resource to the application.

7.      This is OAuth's normal conceptual flow, but the actual authentication flow depends on the type of authorization grant that is used. We will now discuss the different authorization grants available.

Authorization Grant: Client credentials grant

The type of grant used depends on the authorization method the app wishes to use and, of course, of the methods supported by the Web API. To work with the Valuekeep CMMS Web API, you must use the Client Credentials authorization method.

Refresh Token

When an access token expires, its use to perform requests to the API will result in the error “Invalid Token Error”. In that moment, if a refresh token has been included when the access token is generated, you can use it for a new server access token.

Example of a request of that type:



    • Related Articles

    • WebAPI – How do I create work orders?

      This method offers a simple way of creating a Work Order for a specific Asset, Location, Tool or Route. The method to be used to create a work order is: POST /api/mytenant/myorganization/maintenance/workorders/newWorkOrderInfo Json example to create ...

    • WebAPI – How do I update a work order?

      This method offers a simplified way of performing changes to the Work orders. The method to be used to create a work order is:    POST /api/mytenant/myorganization/maintenance/workorders/updateWorkOrderInfo/{{companyKey}}/{{workOrderKey}} The ...

    • WebAPI – How can I change the work order state?

      This method allows you to change a work order state. The method to be used for changing the work order change is: Post {{url}/api/{{tenant}}/{{organization}}/maintenance/workorders/changeSchemaEntityState/{{companyKey}} The parameters in the method ...

    • WebAPI – How do I get work orders assigned to user?

      This method returns the work orders list assigned to each employee of a specific company. The method to be used to get the work orders list assigned to the employee is: GET ...

    • WebAPI – Get work orders and technicians from workshops the authenticated user is responsible for

      This method returns the list of work orders and technicians that belong to the workshops the authenticated user is responsible for. The methods to be used to get the list are: ...