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>/getToken
Note

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

Table 7.1 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=read
Response
<Actual response from the OAuth provider>
Password Grant Type

Request
grant_type=password&client_id=xxxxxxxxxxxxxxx&client_secret=xxxxxxxxxxxxxx&username=
username&password=xxxxxxxxx&scope=read
Response
<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=read
Response
<Actual response from the OAuth provider>

7.2. Validate an access token¶

POST
<base URL>/validateToken
Resource Properties

Table 7.2 Resource 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>/revokeToken
Resource Properties

Table 7.3 Resource 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"
}
```