Authentication Guide

Degreed uses the OAuth 2.0 protocol’s Client Credentials Flow for authentication and authorization. API keys (the combination of a client_id and client_secret credentials) are used to request a bearer access token. When you make an API call, the access token is used to authenticate your identity and your authorization to access resources.

API Keys

You can create API keys using Degreed if you are a Technical Admin with the Manage API Keys permission. For more information, see Create a New API Key. If you need additional scopes, you can request a new API key with the required scopes, or that new scopes be added to an existing key, from your Degreed Technical Solutions Specialist.

Organization Keys vs Provider Keys

API keys can have a specific provider associated with them when they are created. These keys are often called provider API keys. This effectively limits the key to accessing only data associated with that provider. Additionally, any data created with that key will be associated with the provider. This is a security measure to reduce the scope of accessible data. When an external party requires an API key from you, you should give them the minimal scopes required and restrict them to accessing their own data if possible.

Without a specific provider associated with the API key, the API key grants access to data regardless of who created it, limited only by the scopes associated with the key. These keys are often called organization API keys. When accessing your own data via API, this is the kind of key to use.

Additionally, some third-party integrations require access to data they did not create. For example, an integration might require your users' skill data to recommend content. In these situations, a provider API key provides insufficient access. In these cases, you must give the provider an organization key.

Always be careful to give only the scopes necessary for the work to be done with the API key.

Scopes

Scopes are used to control sets of operations and resources that an access token permits. The documentation for each API call includes the required scopes. You can create an API key using Degreed. If you need additional scopes, you can request an API key from your Degreed Technical Solutions Specialist.

❗️

When Creating API Keys, Use Minimal Viable Scopes

When you create API keys, you assign scopes to them. These scopes indicate the endpoints accessible to access_tokens created with the API key. As a general data security principle, we highly recommend that you make your API keys with a minimal number of scopes to enable your integration work to succeed. This approach minimizes the possible harm from compromised keys or tokens.

OAuth Base URLs and Parameters

The OAuth base URL you use to make an access token request depends on the environment (betatest or production) and data center (US, EU, or CA) you are using.

🚧

The access token base URL is not the same as the API base URL used to submit requests.

Use the following OAuth Base URLs when requesting an access token:

degreed.com Domain

degreed.app Domain

Use the following parameters in your request:

Requesting an Access Token

To request an access_token, send an HTTP POST request using an API client such as Postman or Insomnia, or the command line with the required parameters and relevant scopes. Refer to the Access Token endpoint for more information.

This sample request uses the betatest environment OAuth URL:

curl -X POST "https://betatest.degreed.com/oauth/token" \  
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials&client_id=abcd&client_secret=efgh&scope=content:read'

This authentication request returns JSON structured like this:

{
  "access_token": "<access_token>",
  "token_type": "bearer",
  "expires_in": 5183999,
  "refresh_token": "<refresh_token>"
}

The calling application extracts the access_token from the response and then sends the token using an HTTP authorization header with the value in the format Bearer <access_token>.

Access tokens are valid only for the set of operations and resources described in the scope of the token request.

The default access token duration is 60 days. You can request that the duration be modified by contacting your technical support representative.

Include the token in the Authorization header with the Bearer authentication scheme in API calls to authenticate your identity and your authorization to access resources.

This sample request includes an access_token:

curl "https://api.betatest.degreed.com/api/v2/users"
    -H "Authorization: Bearer <access_token>"

The refresh_token token is not useful for API access by parties external to Degreed.

Logging Out

If you want to end your current session with the API, you can use the logout endpoint. When the endpoint is used, it immediately expires the access_token and the refresh_token if provided.

curl "https://api.betatest.degreed.com/oauth/token"
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <access_token>"
  -X POST