Authorize inbound API requests

Inbound API requests are requests that your application sends to AppDirect product APIs. The following are examples of inbound APIs:

• Retrieve details of an event notification from an AppDirect marketplace
• Metered Usage API
• Company Sync API
• User Sync API

When you use the Separate Credentials authorization type, AppDirect generates an OAuth 2.0 client ID and secret that your application uses to retrieve an access token. This access token must be included in the authorization header of all inbound API requests.

📝 Note Client credentials is the only grant type supported for this flow. See the OAuth 2.0 Authorization Framework specification for information about this supported grant type.

Prerequisite

OAuth 2.0 access tokens can only be used within the marketplace they were issued from. Before an access token is requested, your application must first determine the base URL of the AppDirect marketplace it will make API requests against.

For example, if your application must retrieve details of an event notification available at https://www.acme-marketplace.com/api/integration/v1/events/12345, then the marketplace base URL is https://www.acme-marketplace.com

The following diagram illustrates the inbound API request flow:

1. Your application initiates authorization with a POST request to the marketplace’s token endpoint to exchange the client’s credentials for an access token. This request must be authenticated (basic authentication) with the client ID and secret.

AppDirect token endpoints are located at "marketplace\_base\_url/oauth2/token"

Sample request:

curl -X POST -u Q86QDa2JhB:S9GHG6C8ibZDsBcvYwz0 -H 'Content-Type: application/x-www-form-urlencoded' "https://www.acme-marketplace.com/oauth2/token" -d "grant_type=client_credentials&scope=ROLE_APPLICATION"  

In the previous sample, Q86QDa2JhB and S9GHG6C8ibZDsBcvYwz0 are the generated OAuth 2.0 client ID and secret, respectively.

Parameter	Description
grant_type	Must be client_credentials, which indicates that this is the Client Credentials grant type.
scope	Must be ROLE_APPLICATION, which allows product-level API authorization.

2. The requested access token is returned.

"access_token": "sM137PfAbYFQ9gpG...",
"token_type": "bearer",
"expires_in": 43199,
"scope": "ROLE_APPLICATION"

3. Your application calls an AppDirect API and includes the access token in the Authorization header as a bearer token.

Sample request:

curl -H 'Authorization: Bearer sM137PfAbYFQ9gpG...' "https://www.acme-marketplace.com/api/integration/v1/events/12345"

4. Receive the authorized API response.

Token expiration

AppDirect-issued OAuth 2.0 access tokens periodically expire. The expiration time is defined in the expires_in attribute of the token response. Your application must be able to handle token expiration and retrieve new tokens when necessary.