Requesting Application for Third-party Gateway APIs

About this task

When you request for an application to access an API from a third-party gateway, the webhook attached to the gateway communicates the request to the gateway as an event payload.

The gateway then creates API key, JWT, or OAuth access token for the requested API. You can then update the access token credentials in Developer Portal.

The following diagram shows the basic flow of the application approval process:

To request application from third-party gateway:

Request for application to test an API using one of these methods:

Make a REST call to the following endpoint:

POST	 /rest/v1/requests

For example, the following request creates an app Petstore App for invoking the API petstore1

{
    "context": {
        "name": "Petstore App",
        "description": "This application is used for building petstore app",
        "apis": [
            "842c3e33-5c4b-4abf-b827-1a194affde50"
        ]
    },
    "type": "APPLICATION_CREATION_REQUEST"
}

Sample response

{
    "id": "15fe0192-24e4-422a-afa5-58879161b9dc",
    "_self": "/portal/rest/v1/requests/15fe0192-24e4-422a-afa5-58879161b9dc"
}

Sample webhook payload sent to the callback URL of the third-party gateway

{
  "executor": {
    "id": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
    "email": null,
    "lastname": "System",
    "firstname": "Administrator",
    "name": "administrator"
  },
  "source": {
    "id": "842c3e33-5c4b-4abf-b827-1a194affde50",
    "externalref": "24372f80-072e-455f-9235-5c01fbe6f139"
  },
  "contextdata": {
    "consumer_appName": "Petstore App",
    "consumer_appDesc": "This application is used for building petstore app",
    "tenant": "default",
    "redirect_uris": [
      "https://hostname:18152/portal/rest/v1/oauth/callback"
    ],
    "provider_id": null,
    "api_id": "842c3e33-5c4b-4abf-b827-1a194affde50",
    "application_id": "6179b933-1382-4e1a-becc-239dcfeaaa6d"
  },
  "type": "REQUEST_ACCESS_TOKEN",
  "creationdate": "2022-01-10 14:36:14",
  "eventid": "5790ab9a-5312-4122-8aa8-8ca21cf98663",
  "status": "NEW"
}

Request for an application through Developer Portal UI. For detailed information about creating an application request, see Creating an application.

Update the access token credentials (API Key, OAuth, and JWT) in Developer Portal by making REST call to:

PUT	 /rest/v1/applications/{id}?eventId=${eventId}

For example, this request updates the access token required to access the API, petstore1.

PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=5790ab9a-5312-4122-8aa8-8ca21cf98663
{
    "name": "Petstore App",
     "credentials": [
        {
            "expiry": null,
            "apiKey": "709cb14b-f19f-4df9-98b8-eebe727f7844",
            "type": "APIKey"
        },
        {
            "clientId": "3d2404cb-d07d-4101-b38a-f13005b4cc53",
            "clientSecret": "caed6fb3-7fd3-479f-8db5-81b4aeeeba86",
            "scopes": [],
            "tokenLifeTime": 3600,
            "tokenRefreshLimit": 0,
            "authorizationUris": [
                "https://hostname:5543/invoke/pub.apigateway.oauth2/authorize"
            ],
            "accessTokenUris": [
                "https://hostname:5543/invoke/pub.apigateway.oauth2/getAccessToken"
            ],
            "redirectUris": [
                "https://hostname:18152/portal/rest/v1/oauth/callback"
            ],
            "refreshTokenUris": [
                "https://hostname:5543/invoke/pub.oauth/refreshAccessToken"
            ],
            "type": "OAuth2"
        },
        {
            "claimsets": [
                {
                    "name": "JWT default claims set",
                    "claims": [
                        {
                            "key": "app_id",
                            "value": "29cfdae1-c8c5-44d4-9214-5415496d3d4a"
                        }
                    ]
                }
            ],
            "accesstoken_uris": null,
            "type": "JWT"
        }
    ]
}

Sample response

{
    "code": 200,
    "message": "Application is updated successfully"
}

Next steps:

You can share the access tokens generated for an API to other APIs by increasing the scope of the application.

You must raise a request to the third-party gateway to add the new API details to an existing application. The gateway then updates the application, generates a new access token, and sends the token to Developer Portal.

The following example describes how to add an API, petstore2, to the previously created application, Petstore App.

Make a REST call to the following endpoint:

POST	 /rest/v1/requests

Sample request

POST /rest/v1/requests
{
    "context": {
        "application": "6179b933-1382-4e1a-becc-239dcfeaaa6d",
        "apis": [
            "717eaf03-3c59-448e-8acb-7f3a52667932"
        ]
    },
    "type": "APPLICATION_API_REGISTRATION_REQUEST"
}

Sample webhook payload sent to the third-party gateway

PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=ebdcef36-1bf6-4998-9556-9fa38b3785b9
{
    "name": "Petstore App",
     "credentials": [
        {
            "expiry": null,
            "apiKey": "709cb14b-f19f-4df9-98b8-eebe727f7844",
            "type": "APIKey"
        },
        {
            "clientId": "3d2404cb-d07d-4101-b38a-f13005b4cc53",
            "clientSecret": "caed6fb3-7fd3-479f-8db5-81b4aeeeba86",
            "scopes": [],
            "tokenLifeTime": 3600,
            "tokenRefreshLimit": 0,
            "authorizationUris": [
                "https://hostname:5543/invoke/pub.apigateway.oauth2/authorize"
            ],
            "accessTokenUris": [
                "https://hostname:5543/invoke/pub.apigateway.oauth2/getAccessToken"
            ],
            "redirectUris": [
                "https://hostname:18152/portal/rest/v1/oauth/callback"
            ],
            "refreshTokenUris": [
                "https://hostname:5543/invoke/pub.oauth/refreshAccessToken"
            ],
            "type": "OAuth2"
        },
        {
            "claimsets": [
                {
                    "name": "JWT default claims set",
                    "claims": [
                        {
                            "key": "app_id",
                            "value": "29cfdae1-c8c5-44d4-9214-5415496d3d4a"
                        }
                    ]
                }
            ],
            "accesstoken_uris": null,
            "type": "JWT"
        }
    ]
}

Update the application in Developer Portal by making a REST call to:

PUT	 /rest/v1/applications/id?eventId=eventId

Sample request

PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=ebdcef36-1bf6-4998-9556-9fa38b3785b9
{
    "name": "Petstore App",
     "credentials": [
        {
            "expiry": null,
            "apiKey": "709cb14b-f19f-4df9-98b8-eebe727f7844",
            "type": "APIKey"
        },
        {
            "clientId": "3d2404cb-d07d-4101-b38a-f13005b4cc53",
            "clientSecret": "caed6fb3-7fd3-479f-8db5-81b4aeeeba86",
            "scopes": [],
            "tokenLifeTime": 3600,
            "tokenRefreshLimit": 0,
            "authorizationUris": [
                "https://hostname:5543/invoke/pub.apigateway.oauth2/authorize"
            ],
            "accessTokenUris": [
                "https://hostname:5543/invoke/pub.apigateway.oauth2/getAccessToken"
            ],
            "redirectUris": [
                "https://hostname:18152/portal/rest/v1/oauth/callback"
            ],
            "refreshTokenUris": [
                "https://hostname:5543/invoke/pub.oauth/refreshAccessToken"
            ],
            "type": "OAuth2"
        },
        {
            "claimsets": [
                {
                    "name": "JWT default claims set",
                    "claims": [
                        {
                            "key": "app_id",
                            "value": "29cfdae1-c8c5-44d4-9214-5415496d3d4a"
                        }
                    ]
                }
            ],
            "accesstoken_uris": null,
            "type": "JWT"
        }
    ]
}

Decrease the scope of an application by making a REST call to the following endpoint:

POST	 /rest/v1/requests

For example, to remove petstore2 from the previously created application, Petstore App.

POST /rest/v1/requests
{
    "context": {
        "application": "6179b933-1382-4e1a-becc-239dcfeaaa6d",
        "apis": [
            "842c3e33-5c4b-4abf-b827-1a194affde50"
        ]
    },
    "type": "APPLICATION_API_DEREGISTRATION_REQUEST"
}

Sample webhook payload sent to the third-party gateway

{
  "executor": {
    "id": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
    "email": null,
    "lastname": "System",
    "firstname": "Administrator",
    "name": "administrator"
  },
  "source": {
    "id": "6179b933-1382-4e1a-becc-239dcfeaaa6d",
    "externalref": null
  },
  "contextdata": {
    "api": {
      "id": "842c3e33-5c4b-4abf-b827-1a194affde50",
      "externalRef": "24372f80-072e-455f-9235-5c01fbe6f139"
    }
    "application_id": "6179b933-1382-4e1a-becc-239dcfeaaa6d"
  },
  "type": "REVOKE_ACCESS_TOKEN",
  "creationdate": "2022-01-10 15:47:38",
  "eventid": "8115a10f-451f-4cce-9bb6-7beb1e4722d3",
  "status": "NEW"
}

Update the application in Developer Portal by making a REST call to:

PUT	 /rest/v1/applications/id?eventId=eventId

Sample request

PUT /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d?eventId=8115a10f-451f-4cce-9bb6-7beb1e4722d3

Check the status of an application and the list of APIs associated with it by making a REST call to:

GET	 /rest/v1/applications/id

Sample request

GET /rest/v1/applications/6179b933-1382-4e1a-becc-239dcfeaaa6d
 
{
    "name": "Petstore App",
    "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
    "id": "6179b933-1382-4e1a-becc-239dcfeaaa6d",
    "documentType": "APPLICATION",
    "providerRef": "7ecefe01-efc7-43e4-9a19-57c3a761e252",
    "access": {
        "teams": [],
        "users": []
    },
    "apis": [
        "842c3e33-5c4b-4abf-b827-1a194affde50",
        "717eaf03-3c59-448e-8acb-7f3a52667932"
    ],
    "credentials": [
        {
            "expiry": null,
            "apiKey": "709cb14b-f19f-4df9-98b8-eebe727f7844",
            "type": "APIKey"
        },
        {
            "clientId": "3d2404cb-d07d-4101-b38a-f13005b4cc53",
            "clientSecret": "caed6fb3-7fd3-479f-8db5-81b4aeeeba86",
            "scopes": [],
            "tokenLifeTime": 3600,
            "tokenRefreshLimit": 0,
            "authorizationUris": [
                "https://hostname:5543/invoke/pub.apigateway.oauth2/authorize"
            ],
            "accessTokenUris": [
                "https://hostname:5543/invoke/pub.apigateway.oauth2/getAccessToken"
            ],
            "redirectUris": [
                "https://hostname:18152/portal/rest/v1/oauth/callback"
            ],
            "refreshTokenUris": [
                "https://hostname:5543/invoke/pub.oauth/refreshAccessToken"
            ],
            "type": "OAuth2"
        },
        {
            "claimsets": [
                {
                    "name": "JWT default claims set",
                    "claims": [
                        {
                            "key": "app_id",
                            "value": "29cfdae1-c8c5-44d4-9214-5415496d3d4a"
                        }
                    ]
                }
            ],
            "accesstoken_uris": null,
            "type": "JWT"
        }
    ],
    "status": "LIVE",
    "slots": {
        "$stage": "X Gateway"
    },
    "deleted": false,
    "description": "This application is used for building petstore app",
    "app_type": "API"
}

When any application creation, scope increase, or scope decrease transactions fail, you can retry the failed transaction using the following REST calls:

GET	 /rest/v1/applications/applicationId/requests

This request returns the list of requests made for an application by the current user (signed in user or authorization used in the REST call). You must provide the required application Id.

Sample response

{
    "result": [
        {
            "owner": "200ceb26-807d-3bf9-9fd6-f4f0d1ca54d4",
            "id": "0d88fdbf-457b-489f-85bf-fb6678474649",
            "modified": "2022-02-10T12:43+0000",
            "created": "2022-02-10T12:43+0000",
            "documentType": "USER_REQUEST",
            "type": "APPLICATION_CREATION_REQUEST",
            "status": "DELIVERY_UNSUCCESSFUL",
            "application": "8d67856d-476f-492c-a82d-d274501ad08a",
            "state": {
                "7f8060c1-056e-47d1-8785-83a3eb8f5c88": "DELIVERY_UNSUCCESSFUL"
            }
        }
    ],
    "count": 1
}

From the list of requests returned in the response, you can view the failed requests and retry them using the below REST call with the request Id and state Id values:

PUT	 /rest/v1/requests/requestId/retry?state=stateId

Sample response

{
    "code": 200,
    "message": "User request retried successfully"
}