To request the authenticated token, the client software initiates communication through the User-Agent to Modulo Risk Manager. The "Authorization Request" is then sent to Modulo Risk Manager. For this purpose, the following information is sent: response_type, client_id, and redirect_uri. The redirect_uri and the callback URL provided when the application is registered in the system must be the same.
GET {RMUrl}/APIIntegration/AuthorizeFeatures?client_id=6ed521279efd47b883bea4ddef9e617b&response_type=code&redirect_uri=http%3A%2F%2Fhost.com.%2Fapplication HTTP/1.1
Host: modulo.com
Once the "Authorization Request" is received, the system checks if the information received exists and is valid. If valid, the user will be redirected to a screen to authorize use of the features selected when the client software was registered in the system. Once authorized, the system will redirect the user to the redirect_uri provided. The return is an "Authorization Response" with an authorization_code generated by the system.
HTTP/1.1 302 Found
Location: https://intranet.com.br/application?code=f09e5ac6f93e4cb2a2f91f5d2dfa75f
If the system does not validate the information due to some missing or invalid parameter or because of an unregistered redirect URL, it sends the client software an "Authorization Response" with the following information: error and error_description.
HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied
Once authorized, the client software sends the "Access Token Request" to Modulo Risk Manager. To do so, it sends the following information: grant_type, code, redirect_uri, client_id, and client_secret.
POST {RMUrl}/APIIntegration/Token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: modulo.com
Content-Length: 250
Expect: 100-continue
Connection: Keep-Alive
grant_type=authorization_code&
code=f09e5ac6f93e4cb2a2f91f5d2dfa75fa&
client_id=6ed521279efd47b883bea4ddef9e617b&
client_secret=8b108f4368b54a33a11ab0d95f6bf176&
redirect_uri=http%3A%2F%host.com%2Fapplication
Once the "Access Token Request" is received, the system validates the information. For example, it verifies the existence of the client_id, whether or not the client_secret is associated with the correct client_id, and whether or not the authorization_code is valid.
If the system validates the information, it returns an "Access Token Response" to the client software with the following information: access_token, refresh_token, token_type, and expires_in. The system stores the access_token and the refresh_token until their expiration dates. The "Access Token Response" always includes the "HTTP Cache-Control" as "no-store".
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token": "B67F7DF3B6969DEC693F7EDC06BA49B7E5F7F10F",
"refresh_token": "626333EA48628394B1A496984A81335C2740106C",
"token_type": "bearer",
"expires_in": 86400,
}
Once the access_token is received, the client software stores it until its expiration date. In authenticated access, the token is valid for 24 hours (86,400 seconds) by default. Once expired, it should be discarded and cannot be reused. In authenticated access, multiple tokens can be requested for each authorized application.
The refresh_token is a credential used to obtain new access tokens. This is issued to the client by the system and used to obtain a new access token when the current access_token becomes invalid or expires. Refresh tokens are valid for 6 months, by default. They should be discarded once expired and cannot be reused.
Both refresh tokens and access tokens can be revoked in the system. Therefore, the client application should be prepared to handle invalid token responses and to request authorization again from the beginning.
If the system does not validate the information in the "Access Token Request", it sends an "Authorization Response" to the client software with the following information: error, error_description, and error_uri. The error_description and error_uri details are optional. The HTTP error codes are 401 (if the client provided invalid credentials) or 400 (if some other error occurred).
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error":"invalid_request"
}