Watershed supports using both Basic HTTP or OAuth for authorizing xAPI activity providers, importing statements from another LRS and making API requests. This guide explains how to implement and this authorization method.
Please note: Watershed only supports OAuth 2.0 Client Credentials Grant, otherwise known as OAuth 2 Two Legged auth flow as described in the OAuth 2 specification
Activity providers and OAuth
Start by configuring a new Activity Provider in Watershed. Don't forget to give the Activity Provider a memorable name like. Adding an Activity Provider will give you credentials to use for basic authentication, an endpoint url, key and secret which will look something like:
| Endpoint | https://watershedlrs.com/api/organizations/1234/lrs/ |
| Key | 30db41b72cbffb |
| Secret | eb510b89c18441 |
OAuth and Tenant Server URLs
The OAuth and Tenant Server URLs are both based on the start of the Watershed Endpoint but have slightly different endings.
If your Watershed Endpoint is
https://watershedlrs.com/api/organizations/1234/lrs/
then your OAuth Server URL removes the 'lrs' and adds 'oauth2/token' to become
https://watershedlrs.com/api/organizations/1234/oauth2/token
and your Tenant Server URL adds 'statements' to become
https://watershedlrs.com/api/organizations/1234/lrs/statements
Client ID and Secret
The OAuth Client ID and Client Secret are just the Key and Secret from the activity provider, with the Key being the Client ID and the Secret being the Client Secret.
Final configuration
Based on the example activity provider above the full OAuth credentials for the Activity Provider would be:
| OAuth Server URL | https://watershedlrs.com/api/organizations/1234/oauth2/token |
| Tenant Server URL | https://watershedlrs.com/api/organizations/1234/lrs/statements |
| Client ID | 30db41b72cbffb |
| Client Secret | eb510b89c18441 |
Inbound LRS data and OAuth
Go to the Data page. In the menu on the left, click xAPI Data Sources. Inbound LRS Data is the 2nd section down:
- Go to the Inbound Data section and click the and the Add Inbound Data Source button:
- Using data from the outside LRS, fill out the fields. Different LRSs call these different things:
- Name: Name this something that will help you remember what it is.
- Endpoint: Paste in the endpoint URL from the LRS that you’d like to pull statements from.
- Key: Paste in the key, username or client ID from the LRS that you’d like to pull statements from. Please note: this is probably not the username you use to log in to the LRS.
- Secret: Paste in the secret, password, or client secret from the LRS that you’d like to pull statements from. Please note: this is probably not the password you use to log in to the LRS.
- OAuth: Paste in the URL of the Oauth token provider of the LRS you are connecting to.
- Last timestamp: select a timestamp that you want to pull statements after that time.
- Click the Save button. All old statements from the other LRS should show up in your Data Search and so should any future statements made in the other LRS. If you don’t see any imported statements within 15 minutes, you should check your configuration and make sure everything was entered correctly.
Authorizing Watershed API requests with OAuth
This section describes how to utilise OAuth when making a Watershed API request, or when configuring a custom application or activity provider.
Client Credentials Grant
To use OAuth 2.0 authentication, the application sending xAPI data to Watershed first requests a time and scope limited bearer access token, and then uses that bearer access token to authenticate with Watershed's xAPI (and API) endpoints.
Request URL: /api/organizations/[org-id]/oauth2/token
Method: POST
Expected response code: 200 OK
Request headers
|
Header |
Details |
|
Content-Type |
The content type for this request is |
Please note: Authorization and X-Experience-API-Version headers are not used with this request.
Request Form Fields
The following form fields are used:
|
Field |
Description |
Required |
|
grant_type |
The grant type parameter should always have a value of |
Required |
|
client_id |
The activity provider key. |
Required |
|
client_secret |
The activity provider secret. |
Required |
|
scope |
Comma separated list of scopes e.g. xapi:read, xapi:write,xapi:all,wsapi:all. See below for an explanation of scopes. If not specified, defaults to whatever scopes have been granted to the activity provider credentials passed in the client_id and client_secret parameters. |
Optional |
|
expire_seconds |
Number of seconds after which the bearer access token will expire. Defaults to 1 hour (3600 seconds). |
Optional |
Please note: the expire_seconds field is not part of the OAuth 2.0 specification, but is an additional property supported by Watershed so that clients can specify the expiry time.
Response
A successful response will return 200 OK and a JSON object with the following properties:
|
Field |
Description |
|
access_token |
The token to use for authorization when making xAPI requests. |
|
token_type |
This will always be |
|
expires_in |
Number of seconds after which the bearer access token will expire. |
Scopes
The following scopes are supported:
|
Scope |
Description |
|
xapi:read |
Permitted to make GET and HEAD requests to xAPI endpoints that support these methods. |
|
xapi:write |
Permitted to make PUT, POST and DELETE requests to xAPI endpoints that support these methods. |
|
xapi:all |
Permitted to make any xAPI request. |
|
wsapi:all |
Permitted to make requests to Watershed's API as a global admin user. |
Please note: Activity Provider credentials cannot be used to create bearer access tokens with greater permission scope than they are granted. Requests for tokens will not fail in this scenario, but the resulting bearer access token will be restricted to the permissions of the Activity Provider credentials used to create it.
Using Bearer Access Tokens in xAPI Requests
The bearer access token returned by the client credentials grant request can be used to authorize xAPI (and Watershed API) requests. For these requests, the authorization header should take the format:
Authorization: Bearer <access_token>
For example:
Authorization: Bearer ap_session_YXBfc2Vzc2lvbl9mMDhiOWEyNDAzYWI6ZDBlOWUxMTkxZTM5
Please note: Once the access token expires, it cannot be used for authentication and a new token must be requested.