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.

attribution_id is a separate optional parameter on the token request, not a scope; it does not grant or restrict access to anything

Attributing usage to a subconsumer or vendor

By default, Feedback Aide records credit usage against your consumer. If you need a
finer breakdown, for example per department, per environment, or per downstream
customer, add the optional attribution_id parameter to your token request. All
usage from requests made with that token is then recorded against the value you
supply.

attribution_id is not a scope. It does not grant or restrict access to anything,
and it has no effect on the feedback_session_uuid or state scope checks. It is a
separate optional parameter you send alongside grant_type and scope.

Value requirements

Valid examples: dept-math, integration_v2, abc123.

Invalid examples: has spaces, has.dots, has@symbol, team/subteam. An empty
value such as attribution_id= is also invalid, so omit the parameter rather than
sending it empty.

Request one token per attribution_id

The attribution_id is bound to the token at the moment the token is issued. You
cannot change it or override it on individual API requests. To attribute usage to
more than one value, request a separate token for each value.

If your integration caches or pools tokens, include the attribution_id in your
cache key. Reusing a single token across several departments records all of that
usage against whichever value was supplied when the token was issued.

Choosing your values

Values are free-form. They are not checked against any list, so a misspelled value
creates a new, separate attribution value instead of returning an error. Decide on
your values in advance and generate them in code rather than entering them by hand.

Token request code examples

In the examples below, there are three variables that need to be replaced plus one optional field:

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.
4. your-attribution-id - optional. Replace with the value you want to attribute usage to, or remove the `attribution_id` parameter entirely. See [Attributing usage to a department or integration](#attributing-usage-to-a-department-or-integration).

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' \
 -d 'attribution_id=your-attribution-id'

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']

# Optional: attribute this token's usage to a department, integration or environment
attribution_id = 'your-attribution-id'

# 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,
    attribution_id=attribution_id,
)

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'

# Optional: attribute this token's usage to a department, integration or environment
$attribution_id = 'your-attribution-id'

$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',
    'attribution_id' => $attribution_id,
  ],
]);

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.
• If you cache or pool tokens, key the cache on the attribution_id as well as the scopes, so usage is not attributed to the wrong value.

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.