Credentials API

Andrew Downes

April 06, 2017 14:19

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.

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).

Create a new activity provider

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.

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 application/x-www-form-urlencoded.

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

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 headers

Header

Details

Content-Type

The content type for this request is application/x-www-form-urlencoded.

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.

Response

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.