Use Client Credentials Grant Type

OAuth 2.0 describes a number of grants (methods) for a client application to gain access to the resource owner's account.  The grant type depends on the use case.  For MedsAPI, we will use the client credentials grant type which is the simplest of all the grant types. The client credentials grant type is used for confidential client applications that do not make API calls on behalf of a user that logs in.  The access token is issued to the application itself and will expire in 4 hours.  The client credentials grant type uses an authorization server to gain access to its own service account.  The client application can use the client application credentials (client ID and client secret) to receive an access token from the authorization server.  The access token can then be used to access the service account API endpoints on the resource server.  We will describe the client credentials grant type process in terms of roles in the process:

• Client Application - The third party application that is trying to gain access to its own service account.
• Authorization Server - Issues the access token.  
• Resource Server - Hosts the service account resources.

The client credentials grant type is used when applications need an access token for their own account or on behalf of their customer.  We will describe the client credentials OAuth 2.0 grant type process below. 

Make an Access Token Request to the Authorization Server

The first step in the OAuth 2.0 client credentials grant type is for the client application to make an access token request to the authorization server.  The access token request is used to request an access token from the authorization server.  The access token request to the authorization server needs the following parameters:

• client id - The client id given to the application upon registration.
• grant type - OAuth 2.0 grant type that determines the processing flow to be used.  When using the client credentials grant type flow, this value is client_credentials.
• client secret - The client secret given to the application upon registration.
• product - The set of APIs the client is requesting access to. You will need separate tokens for each product set of APIs.  The product can be "dynamed", "dynamedex", "health-library", "dynamed-decisions" or "dynamic-health".
• customer id/group id - Partners should provide the customer id and group id if they are looking for specific customer information.  Some approved partners do not need to specify the customer id/group id for downloading offline Dynamic Health content.

Code Snippet for a Client Application Access Token Request (Node.js):

    const access_token_options = {
        method: 'POST',
        url: 'https://apis.ebsco.com/medsapi/v1/token',
        headers: {
            'Cache-Control': 'no-cache',
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        form: {
            product: '{product}',  
            grant_type: 'client_credentials',
            client_id: '{your_client_id}',
            client_secret: '{your_client_secret}',
            custId: "{cust1}",
            groupId: "{group1}"
      ,}
    };


    // Send the Request
    request(options, function (error, response, body) {
    if (error) throw new Error(error);
    
    // Now process the json response in the body
    });

Authorization Server Returns an Access Token

After receiving the access token request from the client application, the authorization server responds with an access token to the client application.  The client application can extract the access token from the response.

Code Snippet for a Client Application Extracting an Access Token from the Authorization Server Response (Node.js):

    request(access_token_options, function (error, response, body) {
       if (error) throw new Error(error);
       const body_json = JSON.parse(body);
       const access_token = body_json.access_token;
    
    });

Use the API

Now that the client application has an access token, the application is free to make API requests to the application's service account.  All requests to the API from the client application should have an access token in the header.

Code Snippet for the Client Application Sending a Request to the API using the Access Token (Node.js):

    // Form the Request
    const options = {
        method: 'GET',
        url: 'https://apis.ebsco.com/medsapi-partner-dynamic-health/v1/content/custom-articles&customerId=custID',
        headers: {
           accept: 'application/json',
           Authorization: `Bearer ${access_token}` }
     };

     // Send the Request
     request(options, function (error, response, body) {
         if (error) throw new Error(error);
     
         // Now process the json response in the body
     });

Then, the service account resources that the client application has requested are received from the API.

The client credentials grant is used when applications need to request an access token to access resources on behalf of a user for any product that they are subscribed to. The calling application is responsible for persisting the same customerId/groupId for reuse.