The Watershed Credentials API is used to create and manage LRS and Watershed API credentials. This can be used, for example, by an application such as an LMS that provides LRS credentials for launched e-learning courses. In that scenario, a set of credentials can be created for the launch session and then deleted some time after, when the session is complete.
- User Types
- Only Global Adminscan create API credentials required to interact with the API.
- Pricing
- Available on CLO, and Enterprise plans.
- Expertise
- Only experts can use the API.
Please note: This guide is designed to compliment a conversation with us. If you're looking to implement the Credentials API for your activity provider and need assistance, please let us know and we will be glad to help.
Concepts
Activity Provider
API Activity Providers consist of a key and a secret which can be used to authenticate with Watershed in order to perform actions. These actions can relate either to xAPI and Watershed’s LRS, or to various aspects of Watershed’s API. In addition to the key and secret,Activity Providers are associated with certain permissions relating to whether the credentials associated with the Activity Provider can be used to send and retrieve xAPI data, whether they can be used to retrieve xAPI data stored using other credentials, and whether they can be used to interact with Watershed’s API. Each activity provider should represent a separate data source.
Session
Sessions offer a way to create additional sets of short-lived credentials under an activity provider. The typical use case for this is if you are providing credentials for use by client-side content such as an e-learning course and want to provide a set of time and scope limited credentials.
Sessions inherit the permissions of the activity provider they are created under. It is therefore not recommended to create sessions under an activity provider with Watershed API or global LRS permissions.
API
This section outlines the allowed resources and methods of the Credentials API. In order to interact with the people API, you will need authentication credentials and an organization id (org id).
Get a list of activity providers
Request URL: /api/organizations/[org-id]/activity-providers
Method: GET
Expected response code: 200 OK
Response
A successful request will return a JSON object with count and results properties. results contains an array of credential objects (see below); count contains the length of that array.
Create a new activity provider
Request URL: /api/organizations/[org-id]/activity-providers
Method: POST
Expected response code: 200 OK
Request Content
A JSON object representing an activity provider as defined in the entity model below. The key and secret properties are option and will be set by Watershed if not included.
Response
A successful request will return the complete activity provider object in JSON, including the activity provider id. This id can be used to modify and delete the activity provider and to create sessions as required later.
Edit an activity provider
Request URL: /api/organizations/[org-id]/activity-providers/[activity-provider-id]
Method: PUT
Expected response code: 204 No Content
Request Content
A JSON object representing an activity provider as defined in the entity model below. The key and secret properties are option and will be set by Watershed if not included.
Response
A successful request returns no content.
Delete an activity provider
Request URL: /api/organizations/[org-id]/activity-providers/[activity-provider-id]
Method: DELETE
Expected response code: 200 OK
Response
A successful request returns the deleted activity provider.
Create a session
Request URL (by id): /api/organizations/[org-id]/activity-providers/[activity-provider-id]/sessions
Request URL (self): /api/organizations/[org-id]/activity-providers/self/sessions
Method: POST
Expected response code: 200 OK
Please note: Activity Providers credentials can always be used to create sessions under themselves, even if the Activity Provider credentials do not have Watershed API permissions. Use the 'self' request URL listed above to create sessions under the activity provider being used to authenticate the request to create the session.
Request headers
|
Header |
Details |
|
Content-Type |
The content type for this request is |
Request Form Fields
The following form fields are used:
|
Field |
Description |
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 the session is created under. |
Optional |
|
expire_seconds |
Number of seconds after which the session will expire. Defaults to 1 hour (3600 seconds). |
Optional |
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 session credentials with greater permission scope than they are granted. Requests for tokens will not fail in this scenario, but the resulting session credentials will be restricted to the permissions of the Activity Provider credentials used to create it.
Response
A successful request will return the complete session object in JSON, including the session key. This key can be used to extend and delete the session as required later.
Get a session
Request URL: /api/organizations/[org-id]/activity-providers/[activity-provider-id]/sessions/[session-key]
Method: GET
Expected response code: 200 OK
Response
A successful request will return the complete session object in JSON.
Extend a session
Used to reset the number of seconds until expiry. For example, if a session is created at 10:00 for 3600 seconds, and then at 10:52 the session is extended by 3600 seconds, the new expiry time will be 11:52. The new seconds to expiry replace, rather than add to, the existing seconds to expiry.
Request URL: /api/organizations/[org-id]/activity-providers/[activity-provider-id]/sessions/[session-key]
Method: PUT
Expected response code: 200 OK
Request headers
|
Header |
Details |
|
Content-Type |
The content type for this request is |
Request Form Fields
The following form fields are used:
|
Field |
Description |
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 the session is created under. |
Optional |
|
expire_seconds |
Number of seconds after which the session will expire. Defaults to 1 hour (3600 seconds). |
Optional |
Response
A successful request will return the complete session object in JSON, including the session key. This key can be used to extend and delete the session as required later.
Delete a session
Used to immediately expire a session without waiting until the expiry time.
Request URL: /api/organizations/[org-id]/activity-providers/[activity-provider-id]/sessions/[session-key]
Method: DELETE
Expected response code: 200 OK
Response
A successful request will return the complete session object in JSON.
Entity Model
This section outlines the objects used in interacting with the Credentials API.
Activity Provider
An object representing a set of API credentials.
|
Property |
Type |
Description |
|
id |
Integer |
The id of the activity provider. This property is read only and should not be used when creating activity providers. |
|
created |
ISO 8601 timestamp |
When the activity provider was created. This property is read only and should not be used when creating credentials. |
|
version |
Integer |
The version of the activity provider. This increments every time the credentials are edited. This property is read only and should not be used when creating credentials. |
|
name |
String |
The name of the activity provider. This is displayed on the xAPI Data Sources page and used in the authority property of xAPI statements stored using these credentials. |
|
key |
String |
The key to be used in authentication. |
|
secret |
String |
The secret to be used in authentication. |
|
active |
Boolean |
Whether or not the activity provider are active. If false, the credentials will not be accepted regardless of the lrsAccess and watershedApiAccess settings. |
|
lrsAccess |
String |
One of ‘disabled’, ‘isolated’ or ‘global’. If global, the credentials can be used to store and access any data in the LRS. If isolated, the credentials can be used to store any data and access any data stored with those credentials. If disabled, the credentials cannot be used to interact with Watershed’s LRS. |
|
watershedApiAccess |
String |
‘enabled’ or ‘disabled’. Activity Providers with Watershed API access can be used to perform any other global admin action, including creating and editing API credentials. This means they could be used to obtain LRS access, even if lrsAccess is set to ‘disabled’, because they could be used to set lrsAccess to ‘enabled’ or gain access to another set of credentials that have LRS access. Activity Providers with this permission level should be created and handled with care. |
Session
An object representing a session. Sessions are read only.
|
Property |
Type |
Description |
|
providerId |
String Integer | Id of the activity provider the session sits under. |
|
created |
ISO 8601 timestamp | When the session was created. |
|
expireSeconds |
String Integer | Number of seconds the session is set to expire after. |
|
key |
String | The key to be used in authentication. |
|
secret |
String | The secret to be used in authentication. |
|
expiresAt |
ISO 8601 timestamp | When the session will expire. |