Overview

Feedback Aide uses the OAuth authorization framework with the client credentials grant type to handle authentication.

A token with limited scope is used for all API requests. This means the token grants access only to specific resources or actions as specified within the scope. To get a token, you need to authenticate with your Learnosity OAuth key and secret.

To get a token, you need to use your learnosity-oauth-key and learnosity-oauth-secret against the token endpoint - and it will return a token that you can use in your subsequent requests.

Understanding scopes

Scopes define the level of access that the token grants. When requesting a token, you need to specify the scopes that your application requires. Each scope grants access to specific resources or actions.

The required scopes for the Feedback Aide API are:

• api:feedbackaide - Grants access to the Feedback Aide API.
• feedback_session_uuid:{your-feedback-session-uuid}:{permissions}
  Grants access to a specific feedback session specified by the UUID.
  The permissions can be:
  • feedback_session_uuid:{your-feedback-session-uuid}:RO
    Grants read-only access to the feedback session. Use this scope when initializing the API for review.
  • feedback_session_uuid:{your-feedback-session-uuid}:RW
    Grants read and write access to the feedback session. Use this scope when initializing the API for grading.
• state:{grade|review} - Grants access to initializing the API in the given state.
  • state:grade - Grants access to initialize in grading state.
  • state:review - Grants access to initialize in learner review state.

Token request code examples

In the examples below, there are three variables that need to be replaced:

1. your-learnosity-oauth-key - replace with the key provided to you.
2. your-learnosity-oauth-secret - replace with the secret provided to you.
3. your-feedback-session-uuid - replace this with the feedback_session_uuid you want to access.

cURL example

curl -X POST 'https://feedbackaide.learnosity.com/api/token' \
 -u 'your-learnosity-oauth-key:your-learnosity-oauth-secret' \ 
 -d 'grant_type=client_credentials' \ 
 -d 'scope=api:feedbackaide feedback_session_uuid:your-feedback-session-uuid:RW state:grade'

This will return a token as follows:

{
  "access_token": "3e1db5b8-68fd-497d-9221-c98f3d5bb457",
  "token_type": "bearer",
  "expires_in": 7200
}

Python example

1. First, install the required dependencies:

python -m venv oauthenv
source oauthenv/bin/activate
pip install requests requests-oauthlib

2. Create a sample Python code file, called oauth_test.py.

from oauthlib.oauth2 import BackendApplicationClient
from requests.auth import HTTPBasicAuth
from requests_oauthlib import OAuth2Session

# Define the client ID, client secret, feedback_session_uuid and token URL
client_id = 'your-learnosity-oauth-key'
client_secret = 'your-learnosity-oauth-secret'
feedback_session_uuid = 'your-feedback-session-uuid'
token_url = 'https://feedbackaide.learnosity.com/api/token'
scope = ['api:feedbackaide', f'feedback_session_uuid:{feedback_session_uuid}:RW', 'state:grade']

# Create an OAuth2 session and fetch the token
auth = HTTPBasicAuth(client_id, client_secret)
client = BackendApplicationClient(client_id=client_id)
oauth = OAuth2Session(client=client)
token = oauth.fetch_token(token_url=token_url, auth=auth, scope=scope)

print(token)

3. Run the new oauth_test.py file.

python oauth_test.py

4. This will return a token as follows:

{
    "access_token": "3e1db5b8-68fd-497d-9221-c98f3d5bb457",
    "token_type": "bearer",
    "expires_in": 7200
}

PHP example

1. First, install the Guzzle client as it is a secure and recommended way to handle HTTP requests in PHP:

composer require guzzlehttp/guzzle

2. Create a PHP test file as follows:

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
$client = new Client();

# Define the client ID, client secret, feedback_session_uuid and token URL
$client_id = 'your-learnosity-oauth-key'
$client_secret = 'your-learnosity-oauth-secret'
$feedback_session_uuid = 'your-feedback-session-uuid'
$token_url = 'https://feedbackaide.learnosity.com/api/token'

$response = $client->post($token_url, [
  'auth' => [$client_id, $client_secret],
  'form_params' => [
    'grant_type' => 'client_credentials', // Per OAuth spec, must always be included
    'scope' => 'api:feedbackaide feedback_session_uuid:' . $feedback_session_uuid . ':RW state:grade',
  ],
]);

echo $response->getBody();

3. This will return the token as follows:

{
    "access_token": "3e1db5b8-68fd-497d-9221-c98f3d5bb457",
    "token_type": "bearer",
    "expires_in": 7200
}

Best practices

To keep your integration secure and reliable, follow these best practices when implementing OAuth and accessing Feedback Aide.

Handle OAuth on the backend

• Perform OAuth token requests only from your backend service.
• Never run the OAuth flow directly in the browser or client-side code.
• When building SPAs, route all frontend requests through your backend to handle authentication.

Protect credentials and tokens

• Keep client secrets and tokens strictly server-side.
• Do not expose them in frontend scripts or client storage (e.g., localStorage, sessionStorage).
• Use the minimum scopes your application needs to complete a task.

Secure your endpoints

• Require authentication for your token generation endpoint.
• Enforce TLS for all OAuth requests.
• Apply rate limiting to prevent abuse.
• For browser-based apps, add CSRF protection and strict CORS rules.

Next steps

Once you've obtained a token, you can learn how to use it by visiting the Getting Started guide.