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

Credentials

API credentials 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, credentials are associated with certain permissions relating to whether the credentials 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.

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 credentials

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 credential

Request URL: /api/organizations/[org-id]/activity-providers
Method: POST
Expected response code: 200 OK

Request Content

A JSON object representing a credential 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 a the complete credential object in JSON, including the credential id. This id can be used to modify and delete the credential as required later.

Edit a credential

Request URL: /api/organizations/[org-id]/activity-providers/[credential-id]
Method: PUT
Expected response code: 204 No Content

Request Content

A JSON object representing a credential 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.

Create a new credential

Request URL: /api/organizations/[org-id]/activity-providers/[credential-id]
Method: Delete
Expected response code: 200 OK

Request Content

A JSON object representing a credential 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 a the complete deleted credential object in JSON.

Entity Model

This section outlines the objects used in interacting with the Credentials API.

Credential

An object representing a set of API credentials.

Property

Details

Id
Integer

The id of the credentials. This property is read only and should not be used when creating credentials.

Created
ISO 8601 timestamp

When the credentials were created. This property is read only and should not be used when creating credentials.

Version
Integer

The version of the credentials. 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 credentials. 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 credentials 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’. Credentials 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. These credentials should be created and handled with care.

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.