7. Gateway OAuth APIs¶
This section outlines the interface specification of DigitMarket™ API Manager’s OAuth APIs with examples. Common scenarios, such as error conditions apply to all use cases and are highlighted at the end of this document.
All data formats and request types supported by these APIs are JSON.
Base URL
All URLs referenced in this section have the following base URL with Gateway’s NGINX:
http(s)://<gateway_nginx_ip>:<port>/<OAuth Basepath>
Note
‘OAuth Basepath’ is the base path as configured in the OAuth gateway and portal properties.
API Use Cases – Interface Details
7.1. Generate an access token¶
POST  
<base URL>/getTokenNote
All requests for generating an access token must set the content-type as “application/x-www-form-urlencoded “, which will be reflected in the HTTP header field “Content-Type”.
Resource Properties
¶ Field Mandatory? Description grant_type Mandatory for all grant types The grant type using which the access token is created client_id Mandatory for all grant types The client ID of the registered application client_secret Mandatory for all grant types The client secret of the registered application username Mandatory for password grant type The username should be sent with request for password grant type password Mandatory for password grant type The password should be sent with the request for password grant type refresh_token Mandatory for refresh token grant type The value of refresh_token obtained along with an access token issued; used only with refresh_token grant type scope Mandatory for all grant types The scope of the access token that will be issued Error Scenarios
If the scope passed is not allowed for that client application or the scope does not exist, the response is as below (This scenario applies to all grant types):
<Actual response from the OAuth provider>If there was any error at the OAuth Service Provider’s end, then the response is as below (This scenario applies to all grant types):
<Actual response from the OAuth provider>Details for Grant Types
Client Credentials Grant Type
Request
grant_type=client_credentials&client_id=xxxxxxxxxx&client_secret=xxxxxxxxxxxxx&scope=readResponse
<Actual response from the OAuth provider>Password Grant Type
Request
grant_type=password&client_id=xxxxxxxxxxxxxxx&client_secret=xxxxxxxxxxxxxx&username= username&password=xxxxxxxxx&scope=readResponse
<Actual response from the OAuth provider>Refresh Token Grant Type
Request
grant_type=refresh_token&client_id=xxxxxxxxxxxx&client_secret=xxxxxxxxxxxxx&refresh _token=xxxx&scope=readResponse
<Actual response from the OAuth provider>
7.2. Validate an access token¶
POST  
<base URL>/validateTokenResource Properties
¶ Field Mandatory? Description access_token Yes, mandatory The token to be validated Error Scenarios
If the token is invalid, then the response is as below:
<Actual response from the OAuth provider>Request (Request Body)
{ "access_token":"access_token_to_be_validated", }Response
If the given token is valid then the response is as below:
<Actual response from the OAuth provider>
7.3. Revoke an access token¶
POST  
<base URL>/revokeTokenResource Properties
¶ Field Mandatory? Description access_token Yes, mandatory The token to be revoked client_id Yes, mandatory The client_id of the application for which the token was generated Request(Request Body)
{ "access_token":"access_token_to_be_revoked", "client_id":"xxxxxxxxxxxxxxxxxxxxxxx" }Response
If the token has revoked successfully, then the response is as below:
<Actual response from the OAuth provider>If the token revocation fails, then the response is as below:
<Actual response from the OAuth provider>Common Scenarios
The following scenarios are common to all APIs:
- OAuth provider is not reachable The gateway responds with standard REST fault structure predefined in global configuration with the name OAuth Server Unavailable
- OAuth Plugin Error If any error occurs during plugin execution, then the gateway responds with a standard REST fault structure predefined in global configuration with the name OAuth Plugin Error.
- Plugin is unavailable The gateway responds with standard REST fault structure predefined in global configuration with the name OAuth Plugin Unavailable.
- OAuth Request Timeout There is a configurable timeout set for each request sent to OAuth Service Provider and the gateway will close the connection if the response is not received within this timeout period, and will respond with standard REST fault structure predefined in global configuration with the name OAuth Server Request Timeout.
- Invalid oAuth Request URL When an basepath starts with oauth and it is invalid then gateway responds with the message Invalid oAuth Request URL.
7.4. Get the list of all the scopes for an application¶
GET
 
Resource URI
<base URL>/scopes/{client_Id}
Request(Request Body): Not required
Response
[ { "scope": "scope name", "description": "scope description", "cc_expires_in": 3000, "pass_expires_in": 1200, "refresh_expires_in": 3000 } ]
Error Scenarios
If the client Id is invalid, then then Gateway responds with the below fault response:
{ "error": "invalid client id" }
If the request URL is
/oAuth/scopes
, then Gateway responds with the below fault response:{ "Faults": { "FaultCode": "GW_401", "FaultString": "Invalid OAuth Request URL", "detail": { "Fault": { "FAULTCODE": "GW_401", "FAULTDESC": "Invalid OAuth Request URL", "FaultOriginator": "AG", "TransactionID": "29485aba-46a3-4f70-a432-d2c4482be3c4" } } } }
If the request URL is
/oAuth/scopes/
, then Gateway considers this as empty client Id and responds with the below fault response:{ "error": "invalid client id" }
If the get scope API call is requested for an application that is deactivated/inactive, then gateway responds with the below fault response:
{ "error": "application is inactive" }