Degreed uses the OAuth 2.0 protocol’s Client Credentials Flow for authentication and authorization. API keys (the combination of a
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.
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.
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 are used to control sets of operations and resources that an access token permits. The documentation for each API call includes the required scopes. If your API key only needs Users, Content, Required Learning, Completions, or xAPI 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.
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:
|API Base URL
Use the following parameters in your request:
|The way the application gets an access token. Use
client_id given to you by Degreed.
client_secret given to you by Degreed.
|The list of scopes used to control sets of operations and resources that the access token permits. The list must use a comma-delimited data format.
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' \
This authentication request returns JSON structured like this:
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
Access tokens are valid only for the set of operations and resources described in the scope of the token request.
Access token duration is measured in seconds. The default duration is 300 seconds, and you can request that 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
-H "Authorization: Bearer <access_token>"
refresh_token token is not useful for API access by parties external to Degreed.
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.
-H "Content-Type: application/json"
-H "Authorization: Bearer <access_token>"
Updated over 1 year ago