Credentials API

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.

Please note: This guide is designed to complement a conversation with us. If you're looking to implement the Credentials API and need assistance, please let us know and we will be glad to help.

This guide consists of 3 sections:

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: /api/organizations/[org-id]/activity-providers/[activity-provider-id]/sessions
Method: POST
Expected response code: 200 OK

Request Parameters

Parameter

Details

expireSeconds
Integer

Optional. The number of seconds that the session should be kept open for. Defaults to 3600 seconds (1 hour) if not specified. 

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 Parameters

Parameter

Details

expireSeconds
Integer

Optional. The number of additional seconds that the session should be kept open for after this PUT request. Defaults to 3600 seconds (1 hour) if not specified. 

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

Details

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

Details

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.  
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

If you can't find what you need or you want to ask a real person a question, please contact customer support.