API Authentication - OAuth 2.0 - Granular Scopes

Edge Administrators can select granular scopes, allowing organizations to control the methods and endpoints an application can access through Cornerstone's APIs using the OAuth 2.0 API credentials. A "scope" is a mechanism in OAuth 2.0 which is used to limit an external application's access. OAuth 2.0 is an industry-standard authentication and authorization protocol for APIs. Using this protocol reduces the time and effort needed by external developers to integrate with the Cornerstone system.

This means organizations can specify applications' access to individual calls. For example, an organization can specify an application's access to GET /services/api/Recruiting/JobApplicant by choosing the get_jobApplicant scope.

Implementation

This functionality is available to any organization that has purchased Cornerstone APIs or the Reporting API. A purchase inquiry for Cornerstone APIs or the Reporting API can be submitted through the Edge Marketplace.

To access Cornerstone APIs or the Reporting API in the Edge Marketplace, go to: Admin > Tools > Edge and click the Marketplace link. Search for and click the Cornerstone API tile. Click the Setup tab for setup instructions for the API.

Additional information about scopes is available in the API Explorer: https://apiexplorer.csod.com/apiconnectorweb/apiexplorer#/

API Management - Scopes

The Scopes for an API can be added when registering a new OAuth 2.0 application from the API Management page in Edge.

To access the API Management page, go to: Admin > Tools > Edge and click the API Management link. Click the Manage OAuth 2.0 Applications tab.

PERMISSION NAME PERMISSION DESCRIPTION CATEGORY
Edge APIs - Manage Grants ability to manage Edge APIs on the API Management page. Edge

Register New Application

Scopes can be configured during the application registration process. To register an application:

  1. Click the Register New Application button.
  2. Populate the fields on the Register New Application page, including the Application Name, Username, and a validity period, if applicable.
    • Each registered application must be associated with an existing user account, which functions as a service account. This user account is bound to the application and to the client ID and secret.
    • The validity period defines the time period, in seconds, for which an access token is issued. This field is optional. If no value is entered, access tokens will be assigned a default validity period of one hour. The maximum value that can be entered in this field is 86,400 seconds (one day). The minimum value is 300 seconds.
  3. Configure the application's scopes. The Scopes section contains a list of endpoints and operations to which the application needs access. The external application will not be able to access an endpoint or operation if it is not selected on this page. Select any necessary scopes.
  4. Click the Register Application button.
  5. Copy the client ID and secret generated by Cornerstone to use when building your API-based integration. Be sure to save this information for your use, as you will only be shown the secret once.