Use Permission Based Authorization (OAuth)

Use Permission Based Authorization (OAuth)

There are some circumstances where you may want to create a credential that can only perform certain actions within the SCORM Cloud API. Maybe you want to give a client access to freely view all registration data. Or you need to pass a credential to your front end but don’t want to give away the keys to the entire kingdom. Whatever the case, you need a way to provide access to a small subset of data with a time limit on access. Fortunately, we have provided a way for you to do this through the use of OAuth tokens.

Note: Most people do not need to use OAuth tokens. Any request to SCORM Cloud can be made with either an OAuth token or an App ID / Secret Key pair. OAuth tokens are completely optional, but should be used if you need/ want scoped permissions and/ or expiring credentials. The advantages OAuth tokens provide come from additional security measures in scenarios where credentials are shared or fine-grained API access is required.

How Do I Get an OAuth Token?

In order to generate an OAuth token, we first need the App ID / Secret Key pair for the application which is authorized to access the resources you want. This allows us to confirm that you are who you say you are and validate that you have the required access needed. Once we have those credentials, we can generate an OAuth token to gain access to those same resources, limited by the scopes provided in the OAuth token call.

There are two endpoints that allow us to generate OAuth tokens: GetAppToken and CreateToken. Both are functionally the same. We’ll go ahead and use GetAppToken for this example:

curl --location --request POST 'https://cloud.scorm.com/api/v2/oauth/authenticate/application/token' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --header 'Authorization: Basic RTRDWE5SQkZFMDpTZWNyZXRLZXlBYUJiQ2NEZEVlRmZHZ0hoSWlKaktrTGxNbU5uT28=' \
     --data-urlencode 'scope=read:ping' \
     --data-urlencode 'expiration=300'

When you make the above request you will see an OAuth token generated for you to pass in with your future requests:

{
    "access_token": "eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJFNENYTlJCRkUwIiwic2NvcGUiOlsicmVhZDpwaW5nIl0sImlzcyI6Imh0dHBzOlwvXC9kZXYuY2xvdWQuc2Nvcm0uY29tIiwiZXhwIjoxNjYyNDkwNjMwLCJpYXQiOjE2NjI0OTAzMzB9.V5X_rS5cy4qH1bZpuihBGqo-5dIc01BoYdzq-JQaUOlYZOUMRTzJ07QC8lIzgUDFxyG8g0YkP-vC_Y_ws4iXgUU58YkZxmii7Ke60WOoJAttSfnpIYfeUMtoOAVaP_I4Q7kH1fzGw8tWKie1N1_LASls-jZQWTdAmuvLaUPUWkSvzoZH4unYT5rWEXf8TbI9rYM6mDpw94vuE4VKdyHdEO_Vtm8Mq5SPjoO4586ntsP_twAT6yDQkvlP8F9mUk4blM4nGIyldU48NHsKp4EvW2UrcKuk8Y0q04zee9ar2tS7Wz2lSoX3lfZaggzhT692ZWU3mOtirgggEzvk7WhhjW97tmTePoYfmtPYVeTS-38f4AIgQK0HM8yFxaO2r9SXPtQdt6pM_qyIUTn_pOPF1yJkfovqpFd3H9Q010DizHzL7Z_DLXNjTDAEn_DXPfMsknjo39Al2IlIoyYFopy6SYMw4gRardbVizCpHWL4K5rzq291CCElhIi_LkpgrQaHBXlBt7YAn8otbhD-B8mjq7DPJjtzsWnE70y9shJ153hVBSSFhlgxZrgIp8TO34YvcG2N1TA1kI4W6lf9AvL8oR5TtyIQXPe0uAyBmCSnSb4o1NSxOgZUA5ssfjJVo8qi2b6UzcBAYTgap1H_zXB-2CaKuKiFn5ROMH3LQMNBiV8",
    "expires_in": 299,
    "token_type": "Bearer"
}

This token is limited in scope to read:ping and will expire in 300 seconds from the time the call was made. This means it can be used to make calls to the PingAppId API call, but will not be able to work with any other endpoint in SCORM Cloud. It also means that any request made with this token after 5 minutes will immediately fail.

How Do I Use My OAuth Token?

Once you have retrieved an OAuth token you can pass it along with your requests as an HTTP Bearer Auth header:

curl --location --request GET 'https://cloud.scorm.com/api/v2/ping' \
     --header 'Authorization: Bearer eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJFNENYTlJCRkUwIiwic2NvcGUiOlsicmVhZDpwaW5nIl0sImlzcyI6Imh0dHBzOlwvXC9kZXYuY2xvdWQuc2Nvcm0uY29tIiwiZXhwIjoxNjYyNDkwNjMwLCJpYXQiOjE2NjI0OTAzMzB9.V5X_rS5cy4qH1bZpuihBGqo-5dIc01BoYdzq-JQaUOlYZOUMRTzJ07QC8lIzgUDFxyG8g0YkP-vC_Y_ws4iXgUU58YkZxmii7Ke60WOoJAttSfnpIYfeUMtoOAVaP_I4Q7kH1fzGw8tWKie1N1_LASls-jZQWTdAmuvLaUPUWkSvzoZH4unYT5rWEXf8TbI9rYM6mDpw94vuE4VKdyHdEO_Vtm8Mq5SPjoO4586ntsP_twAT6yDQkvlP8F9mUk4blM4nGIyldU48NHsKp4EvW2UrcKuk8Y0q04zee9ar2tS7Wz2lSoX3lfZaggzhT692ZWU3mOtirgggEzvk7WhhjW97tmTePoYfmtPYVeTS-38f4AIgQK0HM8yFxaO2r9SXPtQdt6pM_qyIUTn_pOPF1yJkfovqpFd3H9Q010DizHzL7Z_DLXNjTDAEn_DXPfMsknjo39Al2IlIoyYFopy6SYMw4gRardbVizCpHWL4K5rzq291CCElhIi_LkpgrQaHBXlBt7YAn8otbhD-B8mjq7DPJjtzsWnE70y9shJ153hVBSSFhlgxZrgIp8TO34YvcG2N1TA1kI4W6lf9AvL8oR5TtyIQXPe0uAyBmCSnSb4o1NSxOgZUA5ssfjJVo8qi2b6UzcBAYTgap1H_zXB-2CaKuKiFn5ROMH3LQMNBiV8'

And it will produce the same result as if you were using an App ID / Secret Key pair:

{
    "apiMessage": "pong E4CXNRBFE0",
    "currentTime": "2022-09-05T19:47:19.901Z"
}

Since the tokens can be used to make API requests, it is important to limit the scopes and time the token is valid for as much as possible. For example, a token which belongs to an internal tool which pulls registration data will only need read permissions, not write or delete, more specifically only the read:registration permission. On top of that, the OAuth token should be something you get once and keep for as long as you are actively using it. If the internal tool requires a single request every 10 hours, a new one should be generated each time, but if you are making continuous calls over a 5 minute period, each call can share the same token.