How do I use Watershed xAPI credentials with OAuth 2.0?

Watershed xAPI activity provider credentials can be used with either Basic HTTP or OAuth 2.0 authentication. This guide explains the API requests made by an application implementing OAuth 2.0 authentication for xAPI.

Who can use this feature?
 User Roles
Global Admins can use this feature.
 Pricing 
Available on all plans (Essentials, AnalystCLO, and Enterprise).
 Expertise
Experts can use this feature.

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. This process is known as the "Client Credentials Grant", or "OAuth 2 Two Legged auth flow" and is described fully in the OAuth 2 specification.

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

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

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

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.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.

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