Bright V2 API Specification

Table of Contents

• 1. Introduction
• 2. General Usage
     • 2.1. RESTful API
       • 2.1.1. Determining your :id for create and update
     • 2.2. List of Available Resources
     • 2.3. Special Considerations for Cross-Browser Scripting Restrictions
• 3. Quick Start
     • 3.1. Using The Examples
     • 3.2. Prerequisite Data
     • 3.3. Specifying a results format
       • 3.3.1. Overview
       • 3.3.2. Fetching an XML result
       • 3.3.3. Fetching an JSON result
       • 3.3.4. Fetching a CSV result
     • 3.4. Using Regular Expression Queries
       • 3.4.1. Complex Example
       • 3.4.2. Using Multiple Expressions On The Same Field.
     • 3.5. Specifying the List Of Fields To Be Returned
• 4. Access Modes
     • 4.1. Via Bright API Key
     • 4.2. Via Realm ID and Secret Key
     • 4.3. Via SCORMCloud App ID and Secret Key
• 5. API Modules
     • 5.1. List Of Parameters Available To All Methods
     • 5.2. API Key
       • 5.2.1. Method: create
         • 5.2.1.1. HTTP Model:
         • 5.2.1.2. Parameters
         • 5.2.1.3. Return Data
         • 5.2.1.4. Example:
         • 5.2.1.5. HTTP Codes
     • 5.3. Course
       • 5.3.1. Determining your :id for create and update
       • 5.3.2. Method: Index
         • 5.3.2.1. HTTP Model:
         • 5.3.2.2. Parameters
         • 5.3.2.3. Example
         • 5.3.2.4. HTTP Codes
     • 5.4. Invitation
       • 5.4.1. Method: add_learners
         • 5.4.1.1. HTTP Model
         • 5.4.1.2. parameters
         • 5.4.1.3. HTTP Codes
         • 5.4.1.4. Example
         • 5.4.1.5. Return Data
     • 5.5. Realm User
       • 5.5.1. Method: index
         • 5.5.1.1. HTTP Model
         • 5.5.1.2. parameters
         • 5.5.1.3. HTTP Codes
         • 5.5.1.4. Example
         • 5.5.1.5. Return Data
       • 5.5.2. Method: create
         • 5.5.2.1. Parameters
         • 5.5.2.2. HTTP Codes
         • 5.5.2.3. Example
       • 5.5.3. Method: update (gupdate)
         • 5.5.3.1. Parameters
         • 5.5.3.2. HTTP Codes
         • 5.5.3.3. Example
     • 5.6. Registration
       • 5.6.1. Determining your :id for create and update
       • 5.6.2. Format of return data
       • 5.6.3. Method: index
         • 5.6.3.1. HTTP Model
         • 5.6.3.2. parameters
         • 5.6.3.3. HTTP Codes
         • 5.6.3.4. Example
         • 5.6.3.5. Return Data
       • 5.6.4. Method: create
         • 5.6.4.1. Parameters
         • 5.6.4.2. HTTP Codes
         • 5.6.4.3. Example
       • 5.6.5. Method: launch_url
         • 5.6.5.1. HTTP Model
         • 5.6.5.2. parameters
         • 5.6.5.3. HTTP Codes
         • 5.6.5.4. Example
         • 5.6.5.5. Return Data
     • 5.7. StoredQuery
       • 5.7.1. Method: initialize
         • 5.7.1.1. HTTP Model
         • 5.7.1.2. parameters
         • 5.7.1.3. HTTP Codes
         • 5.7.1.4. Example
         • 5.7.1.5. Return Data
       • 5.7.2. Method: run
         • 5.7.2.1. HTTP Model
         • 5.7.2.2. parameters
         • 5.7.2.3. HTTP Codes
         • 5.7.2.4. Example
         • 5.7.2.5. Return Data
     • 5.8. Template
       • 5.8.1. Method: index
         • 5.8.1.1. HTTP Model
         • 5.8.1.2. parameters
         • 5.8.1.3. HTTP Codes
         • 5.8.1.4. Example
         • 5.8.1.5. Return Data
       • 5.8.2. Method: create
         • 5.8.2.1. Parameters
         • 5.8.2.2. HTTP Codes
         • 5.8.2.3. Example
       • 5.8.3. Method: update (gupdate)
         • 5.8.3.1. Parameters
         • 5.8.3.2. HTTP Codes
         • 5.8.3.3. Example
• 6. Debugging Errors
     • 6.1. Fetching HTTP Error Codes from a GET Request
     • 6.2. Fetching HTTP Error Codes from a POST Request
     • 6.3. Debugging Authentication Errors

1. Introduction

This document describes how to use version 2 of the Bright API.

The Bright API provides programmatic access to a variety of functions provided by the Bright platform, most significantly read and write access to the Bright database. Via the API it is possible to register users, assign courses, generate launch URLs, and query results.

This document details how to get connected to the Bright Server, how to authenticate, and what functions are available via which API calls. It also covers what to do when things go wrong, and how to get more information.

More information about Bright and the Bright platform can be accessed from the Bright Homepage or from the Bright Documentation Site.

Stay current with Bright by adding your email address to our blog feed in the side bar of the Aura Blog.

We want your feedback!!! Please report error or questions to us at Aura Support.

2. General Usage

The Bright API is used to interact with Bright Server. Typical things you might do with Bright are

• access data about learners, courses, registrations.
• You might be querying data or pushing data in.

Regardless, all Bright API calls function in the same way. Fundamentally, the Bright API is a RESTful API, so much of what is covered here should seem familiar if you've worked with a RESTful API before. If not, you may want to familiarize yourself with the concepts here: https://en.wikipedia.org/wiki/Representational_state_transfer .

Source: Wikipedia

2.1. RESTful API

The Restful api of bright is built around our main resource types:

• Bright Api Keys (/bright/api/v2/api_key)
• Course Provider (/bright/api/v2/course_provider)
• Courses (/bright/api/v2/course)
• Custom Endpoints (/bright/api/v2/customer/...)
• Invitations (/bright/api/v2/invitation)
• Launch Histories (/bright/api/v2/launch_history)
• Realm User (/bright/api/v2/realm_user)
• Registrations (/bright/api/v2/registation)
• Stored Queries (/bright/api/v2/template)
• Templates (/bright/api/v2/template)

for each resource type, we follow the following model, where a specific path, http verb and action are consistent depending on the bright resource you are accessing.

HTTP Verb	Path	action	used for
GET	/{{resource}}	index	display a list of all {{resource}} [Note: Bright does not implement this canonical REST action].
GET	/{{resource}}/new	new	return an HTML form for creating a new {{resource}}
POST	/{{resource}}	create	create a new {{resource}}
GET	/{{resource}}/gcreate	create	create a new {{resource}} with a GET request. This is an alias to the POST get request provided to allow the {{resource} to be created from a web browser without using a POST. A variety of cross-domain scripting issues can be addressed using the GET create alias (gcreate).
GET	/{{resource}}/:id	show	display a specific {{resource}}
GET	/{{resource}}/:id/edit	edit	return an HTML form for editing a {{resource}}
PUT	/{{resource}}/:id	update	update a specific {{resource}}
GET	/{{resource}}/gupdate/:id	update	update a specific {{resource}} via a GET request. See the comment on gcreate above.
DELETE	/{{resource}}/:id	destroy	delete a specific {{resource}}

2.1.1. Determining your :id for create and update

Depending on which model you are accessing, the :id record can be specified differently.

When Bright is used to connect with an external course provider (like SCORMCloud), the course provider generated guid can be used for :id. Bright is not strongly tied to any particular course provider, and thus use the following naming convention for external course providers ids:

• registration_guid - this is the ID of a registration in the external course provider
• course_guid - this is the ID of the course in the external course provider

Because Bright considers courses to be provided by a 'course provider', you will see fields returned by the Bright API with names like:

• provider_completed_at
• provider_accessed_at
• provider_error_message

etc. This is an indication that the data is not generated by Bright, but from the external course provider.

Please see the API documentuntation for a particular module to see information on how to correctly specify the :id field.

See the registration section for an example.

2.2. List of Available Resources

• Bright Api Keys (/bright/api/v2/api_key)
• Course Provider (/bright/api/v2/course_provider)
• Courses (/bright/api/v2/course)
• Custom Endpoints (/bright/api/v2/customer/...)
• Invitations (/bright/api/v2/invitation)
• Launch Histories (/bright/api/v2/launch_history)
• Realm User (/bright/api/v2/realm_user)
• Registrations (/bright/api/v2/registation)
• Stored Queries (/bright/api/v2/template)
• Templates (/bright/api/v2/template)

2.3. Special Considerations for Cross-Browser Scripting Restrictions

One thing about the RESTFul architecture is does not interoperate well with cross browser scripting restrictions in modern browsers. Specifically, you are probably aware that you can not POST or PUT data via JSONP which means you can interact with a pure RESTFul API from a web page delivered from a web server other the one hosting the Bright API.

To alleviate this problem, we provide two "GET"-oriented aliases, gcreate and gupdate, that work identically to create and update, and are available via HTTP GET calls.

3. Quick Start

In the section we will quickly work throw the steps of connecting to the Bright API, authenticating, and generating API calls.

3.1. Using The Examples

A quick way to get started is to look at

https://github.com/aura-software/bright-api-examples

It shows two methods of API access:

• Access Key
• Ream Guid/Secret Key

And the most common form of API use cases.

3.2. Prerequisite Data

• Your Bright API URL. This will be provided to you and is based on where your Bright server is installed, and what DNS entry is used to access it. Don't know it? Ask us at support@aura-software.com!

You should also have your Bright Realm ID and Secret key, which can be obtained from Bright Support.

See the section on access modes for your alternatives for authenticating with Bright Server.

For the purposes of this example, we will use the following:

• Bright API URL: https://[BRIGHT URL]/bright/api/v2
• Bright Realm Guid: sJtL8PtZG8S0z9bxkjPQ&
• Bright Realm Secret Key: PcQVlfCTIUebps3T268XKzAXvdzFpgc5svkM0uu38Zw

For your environment, use your realm guid and secret key provided by Bright Support.

With the above information, we can already use our API. To do so, we can test this straight from curl a command line tool that is easy to install on most systems.

When learning the Bright API, we recommend you start by assembling some simple curl commands from your command line in order to get a feel for what is possible.

So let's get our list of courses from our API:

curl 'https://[BRIGHT URL]/bright/api/v2/course.xml?realm_guid=sJtL8PtZG8S0z9bxkjPQ&
realm_secret_key=PcQVlfCTIUebps3T268XKzAXvdzFpgc5svkM0uu38Zw'

If you've executed this correctly, you'll get a result like:

And the result:

  <?xml version="1.0" encoding="UTF-8"?>
  <scorm-cloud-courses type="array">
    <scorm-cloud-course>
      <course-provider-id type="integer">6</course-provider-id>
      <created-at type="datetime">2012-11-26T12:10:40Z</created-at>
      <custom></custom>
      <id type="integer">184</id>
      <metadata>{"title":"ENT Foundation - Post Training QUIZ",
	             "description":"",
				 "duration":"0",
				 "typicaltime":"0",
				 "keywords":null}
 	  </metadata>
      <registration-count type="integer">1</registration-count>
      <sc-course-id>1-507727747154e</sc-course-id>
      <size type="integer">157758</size>
      <title>System Test Course</title>
      <updated-at type="datetime">2013-01-17T16:20:10Z</updated-at>
      <versions type="integer">-1</versions>
    </scorm-cloud-course>
  </scorm-cloud-courses>

3.3. Specifying a results format

The Bright API lets you specify the format of your results, but appending a suffix to the require URL prior to the query string.

3.3.1. Overview

Regardless of API call you are making, you must always specify an interface format when interacting with the Bright API.

This must be specified

• Append to the URL prior to query parameters, like:

[BRIGHT_URL].(format=xml|json|csv]?query_parameters=....

While in previous software versions, in some cases the request format was inferred, and '.json' could be ommitted, this model is deprecated and the request format is now required.

3.3.2. Fetching an XML result

To fetch your results in XML format, append a '.xml' to the url, before the request parameters. For example

https://[BRIGHT URL]/bright/api/v2/course.xml

3.3.3. Fetching an JSON result

Let's say if you are using the API from Javascript, and you'd like your results back as JSON. Easy, just rewrite the URL to use 'course.json' instead of 'course.xml'

curl 'https://[BRIGHT URL]/bright/api/v2/course.json?
sc_app_id=RQIBAXU49I&
sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N'

And the result (formatted for readibility:

[
 {
	 "created_at":"2012-11-26T12:10:44Z",
	 "id":187,
	 "registrations":2,
	 "course_guid":"1-5098f07394cbd",
	 "course_provider_id":6,
	 "size":1599415,
	 "title":"Proktologie",
	 "updated_at":"2012-11-27T22:30:40Z",
	 "versions":-1
 },
 {
	 "created_at":"2012-11-29T16:11:53Z",
	 "id":200,
	 "registrations":1,
	 "course_guid":"1-50b63e903dd43",
	 "course_provider_id":6,
	 "size":2211931,
	 "title":"Proktologie",
	 "updated_at":"2012-12-07T15:48:43Z",
	 "versions":-1
 }
]

3.3.4. Fetching a CSV result

To fetch your results in CSV format, append a '.csv' to the url, before the request parameters. For example

https://[BRIGHT URL]/bright/api/v2/course.csv

3.4. Using Regular Expression Queries

Using regular expression query is simple with the Bright API.

For controllers that support it,

• Registration
• Course

You can specify query paramets like

curl 'https://[BRIGHT URL]/bright/api/v2/course.json?[key-logic]&
title_re=[a title regular expression]&
title_re=[a second regular expression]&
custom_re=[a matching expression on the custom field]
...

3.4.1. Complex Example

In this example, we have a "pts available" field in the course custom field.

The query below selects out courses that have a number of points available >= 4.

wget -qO- 'https://[BRIGHT URL]/bright/api/v2/course.json?[key logic]&
custom_re=points_available\":\"([4-9]|[1-9]([0-9])+)'

3.4.2. Using Multiple Expressions On The Same Field.

It is possible to repeatedly query the same field from multiple regular expressions. To do this, use a numerical suffix on the query parameter. So instead of custom_re, for example, use

• custom_re0
• custom_re1

etc.

wget -qO- 'https://[BRIGHT URL]/bright/api/v2/course.json?[key logic]&
custom_re0=points_available\":\"([4-9]|[1-9]([0-9])+)&custom_re1="category":"onboarding"'

Note:

• This search is full text, including in custom [JSON] text.
• Therefore you must support JSON syntax include ':' assisgments.

3.5. Specifying the List Of Fields To Be Returned

You can specify a set of fields to be returned by a Bright API call. This is an alternative method to use the "template=" approach.

To use the fields specification, just include the

 fields=field1,field2,...

query paramters.

For example, on the course controller, when using 'include_registrations', the following is valid:

fields=course_guid,title,custom,registrations.complete,registrations.registration_guid

4. Access Modes

The Bright API can be accessed to two different ways:

• Bright API Key
• Brigh Realm GUID and Secret Key
• SCORMCloud App ID and Secret Key

If you do not specify a valid access mode in your request, you will receive HTTP code 401 (Unauthorized) in your response.

If you specify multiple authentication models, you will received a 501 (not implemented).

4.1. Via Bright API Key

The API Key interface allows for the creation of API keys for Bright Server.

If you want to access the Bright API from some browser side Javascript, using the SCORMCloud or Bright Realm secret key is no good. NEVER put your Secret Key into the browser via Javascript.

Instead the Bright API allows you to create an authentication token that you can use to send to the browser. When you generate this token, typically you specify

• the SCORMCloud app id/secret key OR bright realm secret key
• optionally the user

These application tokens are disabled after a short period of time. Do not hard code the use of a Bright API key, as these keys expire after a period of time.

Here's an example of getting an API token. This first call creates a special access token to a specific user for a specific SCORMCloud application. The key that is returned is suitable for embedding in a web page for use by browser side Javascript.

curl 'https://[BRIGHT URL]/bright/api/v2/api_key/create?sc_app_id=RQIBAXU49I
&sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N
&user_email=admin@aura-software.com'
(returns) df8d1350a6b31378a86b967767f4bba1

You can now omit the secret key and app id from subsequent calls and just use the API key:

curl 'https://[BRIGHT URL]/bright/api/v2/course.xml?\
api_token=bdb273e9cdace9698c34d97070cb392d'

This API token is now "bound" to the access level specified when the key was created.

4.2. Via Realm ID and Secret Key

Your Bright realm ID and secret key will be furnished to you by Bright support. For many functions it is not necessary. If you aren't working with invitations, creating user records on the fly, or using multiple course providers, you probably won't need a Realm key. Note you do not need to create a user to assign a user to a course. This is done on the fly and if you aren't populating custom metadata for a user, it is not necessary to pre-populate the user.

If you need to use a realm ID and secret key, it will be provided to you by Aura support. You can file a request at support@aura-software.com

For the purposes of this example, we will use the following:

• realm_guid: sJLtP8Zt8G0Sbz9kxPjQ
• realm_secret_key: PcVQflTCUIbe3ps2T86KXAzvXzdpFcgs5Mvku03uZ8w

With these, lets create an api key 'bound' to this authentication level:

curl 'https://[BRIGHT URL]/bright/api/v2/api_key/gcreate?
realm_guid=sJLtP8Zt8G0Sbz9kxPjQ&
realm_secret_key=PcVQflTCUIbe3ps2T86KXAzvXzdpFcgs5Mvku03uZ8w'

And the response:

{
 "access_token":"2a84a6ddb229c13bc945874b69fab8ba",
 "course_provider_id":null,
 "created_at":"2013-07-03T00:25:37Z",
 "expires_at":null,
 "id":2038,
 "realm_id":4,
 "token_type":null,
 "updated_at":"2013-07-03T00:25:37Z",
 "user_id":null
}

We can now use the "access_token" returned as an API key in an insecure situation:

curl 'https://[BRIGHT URL]/bright/api/v2/course?
api_key=2a84a6ddb229c13bc945874b69fab8ba'

Or in a secure situation, you can use the realm key directly:

curl 'https://[BRIGHT URL]/bright/api/v2/course?
realm_guid=sJLtP8Zt8G0Sbz9kxPjQ&
realm_secret_key=PcVQflTCUIbe3ps2T86KXAzvXzdpFcgs5Mvku03uZ8w'

4.3. Via SCORMCloud App ID and Secret Key

This sections describes authentication using the SCORMCloud secret key and app id.

If you are using a SCORMCloud course provider, API access can be provided using your SCORMCloud APP ID and secret key. These are available from Aura Support, or from the SCORMCloud console available at https://cloud.scorm.com.

• The SCORMCloud APP ID for your SCORMCloud Application.
• The SCORMCloud Secret Key for your SCORMCloud Application.

Here's an example of fetching these values from the SCORMCloud administration console:

You can access this by selection "Apps" from the SCORMCloud administration console left hand menu.

Access via SCORM Cloud app ID and secret key is deprecated and may be removed at a later date.

You should NEVER share the APP ID and secret key since this give complete access to all of your data.*

Example:

curl 'https://[BRIGHT URL]/bright/api/v2/course.xml?sc_app_id=RQIBAXU49I&
sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N'

If you've executed this correctly, you'll get a result like:

And the result:

  <?xml version="1.0" encoding="UTF-8"?>
  <scorm-cloud-courses type="array">
    <scorm-cloud-course>
      <course-provider-id type="integer">6</course-provider-id>
      <created-at type="datetime">2012-11-26T12:10:40Z</created-at>
      <custom></custom>
      <id type="integer">184</id>
      <metadata>{"title":"ENT Foundation - Post Training QUIZ",
	             "description":"",
				 "duration":"0",
				 "typicaltime":"0",
				 "keywords":null}
 	  </metadata>
      <registration-count type="integer">1</registration-count>
      <sc-course-id>1-507727747154e</sc-course-id>
      <size type="integer">157758</size>
      <title>System Test Course</title>
      <updated-at type="datetime">2013-01-17T16:20:10Z</updated-at>
      <versions type="integer">-1</versions>
    </scorm-cloud-course>
  </scorm-cloud-courses>

The above example will show all courses for the course provider defined by the SCORMCloud data (app id, secret key).

5. API Modules

Note not all RESTFul functions are implemented.

If you encounter an restful API method that is not implemented, please let us know at support@aura-software.com.

5.1. List Of Parameters Available To All Methods

For the API documentation that follows, for the sake of brevity we will omit in the description of each individual method the generic parameters that can be passed to each method.

These are described in more depth here:

• Response Format
• Access Modes
• Using Regular Expression Queries
• Specifying the List Of Fields To Be Returned

Parameters related to response format:

Parameter	Example	Description
format	format=(json|xml|csv)	Specify the format of the response

Parameters related to access method:

Note, you must specify ONE OF:

• api_token
• realm_guid AND realm_secret_key
• sc_app_id AND sc_secret_key [DEPRECATED]

Parameter	Example	Description
sc_app_id	sc_app_id=[a valid sc_app_id]
sc_secret_key	sc_secret_key=[a valid sc_secret_key]
realm_guid	realm_guid=[a valid realm_guid]
realm_secret_key	realm_secret_key=[a valid realm_secret_key]
api_token	api_token=[a valid api_token]
accessToken	accessToken	For historical reasons this is a synonym of api_token

Parameters that control the data to be returned.

See specifying the list of fields to be returned for more information.

Parameter	Example	Description
fields	fields=[field1,...]	specifying the list of fields to be returned
api_template	api_template=(public	public_minimum)

5.2. API Key

The API Key interface allows for the creation of API keys for Bright Server.

5.2.1. Method: create

Create a new API key.

5.2.1.1. HTTP Model:

Verb	Form
Post	(http|https)://BRIGHT_URL/bright/api/v2/api_key?param1=value1&...

5.2.1.2. Parameters

Parameter	Example	Notes
sc_app_id		(optional) You must use either sc_app_id and sc_secret_key OR realm_guid and realm_secret_key.
sc_secret_key		(optional)
realm_guid		(optional) You must use either sc_app_id and sc_secret_key OR realm_guid and realm_secret_key.
realm_secret_key		(optional)
user_email	user_email=jane.doe@me.com	(optional). When specifying a user email when generating an API key, this api key will be "bound" to this user and will be unable to access data unrelated from the user. If you do not set user_email, the generated token will have unlimited (administrative) access to the SCORMCloud application or Bright Realm specified. If you specify an email that is new to the system, an account is automatically created for that user, and the new user is attached as a subscriber class user to the Bright Realm attached to the this SCORM Cloud application.

5.2.1.3. Return Data

Returns a JSON document of the new record. HTTP Code is set to 201 (item created).

5.2.1.4. Example:

curl -w "%{http_code}" -d 'sc_app_id=RQIBAXU49I
&sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N
&user_email=admin@aura-software.com' https://[BRIGHT URL]/bright/api/v2/api_key/

{
 "access_token":"a440b1ad868bc76716d22b4b827db77e",
 "created_at":"2012-12-18T12:16:29Z",
 "expires_at":null,
 "id":139,
 "course_provider_id":6,
 "token_type":null,
 "updated_at":"2012-12-18T12:16:29Z",
 "user_id":12
}
201

Note that this is a POST request, so you must configure your client appropriately. In the case of curl, this is accomplished with the -d flag.

The '-w %{http_code}' piece allows you to view the returned HTTP code.

5.2.1.5. HTTP Codes

Code	Description
201	Success; item created
401	If you do not specify a valid sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP error 401 (unauthorized).
500	If you specify a user_email that is not valid, you will receive a 500 server error.

5.3. Course

5.3.1. Determining your :id for create and update

For courses, Bright maintains a GUID that can be used as the :id field when using create, update, gcreate, or gupdate methods.

If course provider is SCORMCloud, this will be identical to the SCORMCloud course id.

For other course providers, the GUID will be a Bright generated unique ID.

5.3.2. Method: Index

The index method allows the api user to fetch a course list.

When using the course#index method with an Api key, where the API key is for a particular learner, it is often desireable to return the learner's registration data on each course selected. This lets the API client avoid having to query the learner's data for each course returned. You can do this with the include_registrations parameter.

5.3.2.1. HTTP Model:

Verb	Form
GET	(http|https)://BRIGHT_URL/bright/api/v2/course[.format]?param1=value1&...

5.3.2.2. Parameters

All Bright API calls respond the parameters specified in List of Parameters Available To All Methods.

Parameters unique to this method, not included in above:

Control Parameters

Control parameters are not filters and cannot be used with Using Regular Expression Queries.

Parameter	Example	Description
include_registrations	include_registrations=t	When access is via accessToken, with an associated user, a nested record showing the user's most recent registration to the course.

Filter Parameters

Filter parameters restrict the rows to be returned. Any filter parameter can be used with a regular expression, see Using Regular Expression Queries.

Parameter	Example	Description
course_guid	course_guid=ACourseID	For a SCORMCloud course, this will match the course ID in scormcloud. See also Finding Your Course ID in SCORMCloud.
title	title=My%20Course	An exact match of the course Title. Don't forget to URI encode your data.
custom	custom=SomeCustomText	An exact match of the course custom. Don't forget to URI encode your data. Much more useful with 'custom_re', as described in Using Regular Expression Queries
id	id=[a course GUID]	As the Course GUID is the unique identifier for the course, it can be addressed via the id= construct

5.3.2.3. Example

curl -w "%{http_code}" 'https://[BRIGHT URL]/bright/api/v2/course.json?course_guid=16-4fbd9ea698bce

5.3.2.4. HTTP Codes

Code	Description
200	Success; items returned
401	If you do not specify a valid api_key, sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP error 401 (unauthorized).
500	An illegal request, such as a malformed argument.

5.4. Invitation

5.4.1. Method: add_learners

5.4.1.1. HTTP Model

Verb	Form
GET	(http|https)://BRIGHT_URL/bright/api/v2/invitation/add_learners[.format]?param1=value1&...

5.4.1.2. parameters

Parameter	Example	Notes
__access method__	One of: api_key=xxxxxxxxxx [an api key created previously] realm_guid=XXXXXXXXX&realm_secret_key=YYYYYYYYYY [a valid Bright Realm GUID/secret key pair]	see [Access Modes](#access-modes)
api_template	api_template=(public|extended)	When set to "extended", the response will include three fields, "record", "messages", and "registration_guids". The "record" is the invitation, and "registration_guids" includes a complex document that can be used to determine if the user in question actualy received their course registrations. This is high useful in the case of invitations used implement license keys. For this type, a user can be added to an invitation without seats available for one or more courses. In this case, the registration_guids document can be used to determine if the user is actually registered to the courses associated with the invitation. Messages contains information from the license key processor relevant for user feedback.
learners	learners=["users1@exampledomain.com","user2@anotherexample.com"]	URI encoded array of strings, where each string is an email address. These learners will be added to the invitation, and will receive registrations for the courses associated with the invitation [license data dependent].
name	name=myinvitation	you must specify the invitation by name. Failure to do so, or to specify a valid invitation name, will result in a return code of 404
nodelay	nodelay=true	External initialization of registrations will occur synchronously [request will block until they are completed]. The default is asynchronous initialization
skip_external_initialization	skip_external_initialization=true	Useful in tests scenarios. The registrations created won't be externally initialized in the course provider like SCORMCloud
unlearners	unlearners=["users1@exampledomain.com","user2@anotherexample.com"]	URI encoded array of strings, where each string is an email address. These learners will be removed from the invitation. Associated registrations will be marked inactive.

5.4.1.3. HTTP Codes

Code	Description
200	Success; items returned. If show_registration_guids is set to true, the return document is altered. See the documentation for that parameter for more information.
401	If you do not pass a valid realm_guid/realm_secret_key, you will receive HTTP 401
404	(not found); The value passed in via your name parameter did not match an invitation for this realm
500	An illegal request, such as a malformed argument

5.4.1.4. Example

curl -w "%{http_code}" 'https://[bright-url]/bright/api/v2/invitation/add_learners.json?nodelay=1&api_template=extended&name=xxx&learners=%5B%22admin%40aura-software.com%22%5D&realm_guid=sJtL8PtZG8S0z9bxkjPQ&realm_secret_key=PcQVlfCTIUebps3T268XKzAXvdzFpgc5svkM0uu38Zw'

5.4.1.5. Return Data

If api_template request parameter isn't set to extended, the API will respond with the invitation document:

{
  "id": 103,
  "license": true,
  "avoid_duplicate_registrations": false,
  "custom": "{\"license\":true,\"order_id\":10592,\"course_guids\":[\"0215JCHCMscorm12.3cdd5a65-0ec2-44a-c5a1f-37d9283757ce\"],\"license_data\":{\"2051JCHMCscorm1.23cdd56a-5e0c2-44ac-a51f-739d283757ce\":{\"seats_available\":5}},\"initiating_site\":\"localhost\",\"initiating_user\":\"support@aura-software.com\"}",
  "description": null,
  "enabled": true,
  "learners": [
    "support@aura-software.com"
  ],
  "name": "this73807a",
  "no_updates_allowed": false,
  "course_guids": [
    "2c3dd5a65-0ec2-44ac-a51f-37d9283757ce"
  ],
  "registration_guids": [
    "895-XWv_74NgkYTl03_zXIqXwg",
    "895-DY11XFd4ooLiJeGcx7HE3w"
  ],
  "realm_id": 1
}

When api_template is set to extended, the response looks like:

{
  "record": {
    "id": 103,
    "created_at": "2015-11-25T16:40:27.914Z",
    "updated_at": "2015-11-25T16:40:27.914Z",
    "realm_id": 10,
    "name": "this73807a",
    "description": null,
    "enabled": true,
    "custom": "{\"license\":true,\"order_id\":10592,\"course_guids\":[\"2c3dd5a65-0ec2-44ac-a51f-37d9283757ce\"],\"license_data\":{\"2c3dd5a65-0ec2-44ac-a51f-37d9283757ce\":{\"seats_available\":5}},\"initiating_site\":\"localhost\",\"initiating_user\":\"support@aura-software.com\"}",
    "avoid_duplicate_registrations": false,
    "no_updates_allowed": false,
    "invitation_template_id": null,
    "license": true,
    "course_guids": [
      "2c3dd5a65-0ec2-44ac-a51f-37d9283757ce"
    ],
    "learners": [
      "support@aura-software.com"
    ]
  },
  "registration_guids": {
    "support@aura-software.com": {
      "2c3dd5a65-0ec2-44ac-a51f-37d9283757ce": {
        "title": "My Course",
        "registration_guid": "895-XWv_74NgkYTl03_zXIqXwg"
      }
    }
  },
  "messages": [
    "Success!  Found and reused existing registration (895-XWv_74NgkYTl03_zXIqXwg) for support@aura-software.com on 'My Course' as part of license 'this73807a'."
  ]
}

5.5. Realm User

For learners, its generally not necessary to prepopulate realm users as creating a registration implicitly creates the user.

It is possible to create them via the API and also manipulate their custom field as well.

5.5.1. Method: index

5.5.1.1. HTTP Model

Verb	Form
GET	(http|https)://BRIGHT_URL/bright/api/v2/realm_user[.format]?param1=value1&...

5.5.1.2. parameters

Parameter	Example	Notes
__access method__	One of: api_key=xxxxxxxxxx [an api key created previously] realm_guid=XXXXXXXXX&realm_secret_key=YYYYYYYYYY [a valid Bright Realm GUID/secret key pair]	see [Access Modes](#access-modes)
email	email=jane.doe@me.com	filter results to just this email address.

5.5.1.3. HTTP Codes

Code	Description
200	Success; items returned
401	If you do not specify a valid api_key, sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP 401
500	An illegal request, such as a malformed argument

5.5.1.4. Example

5.5.1.5. Return Data

5.5.2. Method: create

Creates a new realm user. You must use a realm guid and secret key (or api key creating bound to a realm key) to create a realm user.

5.5.2.1. Parameters

Parameter	Example	Notes
__access method__	api_key=[an api key created previously]	see Access Modes. You cannot use a SCORMCloud app-id/secret key or user bound api key to create a realm user.
email	email=bret@aura-software.com	email address of the user (required)
realm_role_id	realm_role_id=1	Define the realm role. Not required, defaults to '1' (learner).
custom	custom='{this:that}'	Define a custom field for this user. Custom fields are freeform metadata available to be defined for the user.

5.5.2.2. HTTP Codes

Code	Description
201	Success; item created
302	Item already exists, not modified.
500	If you specify a user_email that is not valid, or a valid course_guid, you will receive a 500 server error.

5.5.2.3. Example

curl -w "%{http_code}" 
'https://[BRIGHT URL]/bright/api/v2/realm_user/gcreate.xml?
api_key=2a84a6ddb229c13bc945874b69fab8ba&
email=bretx@aura-software.com&
custom=foo'
<?xml version="1.0" encoding="UTF-8"?>
<realm-user>
  <created-at type="datetime">2013-07-03T05:26:21Z</created-at>
  <custom>foo</custom>
  <id type="integer">1743</id>
  <realm-id type="integer">4</realm-id>
  <realm-role-id type="integer">1</realm-role-id>
  <updated-at type="datetime">2013-07-03T05:26:21Z</updated-at>
  <user-id type="integer">1686</user-id>
</realm-user>
201

5.5.3. Method: update (gupdate)

Update a realm user. You must use a realm guid and secret key (or api key creating bound to a realm key) to update a realm user.

5.5.3.1. Parameters

Parameter	Example	Notes
__access method__	api_key=[an api key created previously]	see Access Modes. You cannot use a SCORMCloud app-id/secret key or user bound api key to create a realm user.
email	email=bret@aura-software.com	email address of the user (required)
custom	custom='{this:that}'	Define a custom field for this user. Custom fields are freeform metadata available to be defined for the user.

5.5.3.2. HTTP Codes

Code	Description
200	Success; item created
404	Realm user cannot be found..
500	If you specify a user_email that is not valid, or supply unexpected parameters, you will receive a 500 server error.

5.5.3.3. Example

curl -w "%{http_code}" 
'https://[BRIGHT URL]/bright/api/v2/realm_user/gupdate.xml?
api_key=2a84a6ddb229c13bc945874b69fab8ba&
email=bretx@aura-software.com&
custom=foox'
200

5.6. Registration

5.6.1. Determining your :id for create and update

For registrations, Bright maintains a GUID that can be used as the :id field when using create, update, gcreate, or gupdate methods.

If course provider is SCORMCloud, this will be identical to the SCORMCloud registration id.

For other course providers, the GUID will be a Bright generated unique ID.

5.6.2. Format of return data

Field Name	Example Data	Description
attempts	12	This is the # of attempts of the course, as recorded in SCORMCloud.
complete	"complete"	This is the SCORM 'completion' status as recorded in SCORMCloud.
course_result	"\ncompletefailed950"	The course_result is populated by SCORMCloud and is an XML document that shows the SCORM data collected for the registration. For the format of the course result, see https://cloud.scorm.com/doc/web-services/api.html#rustici.registration.getRegistrationResult where resultsformat is "course".
crawl_error_msg		If there is an error crawling this registration, the error message is listed here.
crawl_status	"success"	Last crawl status for the registration. Used internally in Bright.
crawl_type	"course"	Shows the value of "resultsformat" that we used when crawling the registration result. See also https://cloud.scorm.com/doc/web-services/api.html#rustici.registration.getRegistrationResult
created_at	"2012-12-21T08:46:36Z"	The timestamp for the record when created in Bright. This is not the time the record was created in SCORMCloud.
custom	{my_custom_data: 1}	Any user defined custom JSON data. This data can be used to build custom functionality into your Bright Embedder.
full_result	null	If your crawler is running in 'full' mode, (see type), the full results document from https://cloud.scorm.com/doc/web-services/api.html#rustici.registration.getRegistrationResult is available here.
id	5426	The Bright internal ID for this registration.
last_crawled_at	"2012-12-26T14:27:20Z"	Datetime the record was last crawled.
launched_at	"2012-12-26T14:27:00Z"	When this registration is launched from Bright, we maintain a local timestamp of the course launch here. This timestamp can be used via the Bright API to force a recrawl of the registration (using the refresh_if_launched parameter.) See the Bright API document for more information.
learner_id	"bret@aura-software.com"	Email address of the person to whom this registration belongs.
number_of_crawl_errors	0	If there is crawl errors, this counter is incremented.
provider_completed_at	null	This is the completed_at field as record in SCORMCloud. SCORMCloud will set this field when it marks the course completed.
course_guid	"1-50a38b0d9b2bf_0102b60a8-3bc5-4840-8c90-d1fd01a630c3"	The SCORMCloud Course ID.
provider_created_at	null	The timestamp recorded in SCORMCloud as to when the registration was completed. Typically you would use this when displaying data to the user instead of at, which is internal to Bright.
deleted	null	Will be set to a 1 if the registration has been deleted in SCORMCloud.
provider_errcode	null	If we receive an error interacting with SCORMCloud for this registration, the error code will be recorded here.
provider_error_message	null	Error message received from SCORMCloud when attempting to access this registration.
provider_accessed_at	null	The timestamp recorded in SCORMCloud recording the last time the course was accessed.
registration_guid	"1-50a38b0d9b2bf_0102b60a8-3bc5-4840-8c90-d1fd01a630c3-65a9ae1bd2f690a3bc789d6a9299b51e"	The SCORMCloud registration ID.
score	0.0	This is the score for the registration recorded in SCORMCloud.
scorm_cloud_app_id	10	An internal Bright variable corresponding to this SCORMCloud application.
scorm_cloud_course_id	525	An internal Bright variable corresponding to this SCORMCloud course.
success	"failed"	The value of the registration success field recorded in SCORMCloud.
totaltime	95.0	The value of the totaltime field recorded in SCORMCloud.
updated_at	"2012-12-26T14:27:20Z"	The last time this record was updated in Bright.

5.6.3. Method: index

The index method allows the api user to query registrations.

5.6.3.1. HTTP Model

Verb	Form
GET	(http|https)://BRIGHT_URL/bright/api/v2/registration[.format]?param1=value1&...

5.6.3.2. parameters

Parameter	Example	Notes
__access method__	One of: api_key=xxxxxxxxxx [an api key created previously] sc_app_id=XXXXXXXXX&sc_secret_key=YYYYYYYYYYY [a valid SCORMCloud app ID/secret key pair] realm_guid=XXXXXXXXX&realm_secret_key=YYYYYYYYYY [a valid Bright Realm GUID/secret key pair]	see [Access Modes](#access-modes)
last_only	last_only=t	when included in the parameter string, we will return a single registration record, that being the last one created. Useful in cases where multiple registrations are found and only the most recent one should be returned.
course_guid	course_guid=[a scorm cloud course id]	filter results to just this SCORMCloud course ID
learner_id	learner_id=jane.doe@me.com	filter results to just this email address.
refresh_if_launched	refresh_if_launched=t	if the last launch date of this registration is newer than the last crawl date, this will force the record to recrawl prior to returning a result.
crawl	crawl=t	forces the registration to recrawl

5.6.3.3. HTTP Codes

Code	Description
200	Success; items returned
401	If you do not specify a valid api_key, sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP
500	An illegal request, such as a malformed argument

5.6.3.4. Example

curl -w "%{http_code}" 'https://[BRIGHT URL]/bright/api/v2/registration.json?
api_key=2a84a6ddb229c13bc945874b69fab8ba&
learner_id=bret@aura-software.com&
course_guid=16-4fbd9ea698bce

5.6.3.5. Return Data

5.6.4. Method: create

Creates a new registration. Can be used in a single call that can be used to return an existing registration if one exists, or create a new one if it does not.

5.6.4.1. Parameters

Parameter	Example	Notes
__access method__	api_key=[an api key created previously]	see Access Modes
sc_app_id	sc_app_id=XXXXYYYYZZZ [a valid app ID]	SCORMCloud application ID (required)
sc_secret_key	sc_secret_key=XXXXYYYYZZZ [a valid app secret key]	SCORMCloud application secret key (required)
course_guid	course_guid=16-4fbd9ea698bce	SCORMCloud course ID (required)
learner_id	learner_id=bret@aura-software.com	email address of user (required)
dont_duplicate	dont_duplicate=t	check for an existing registration for this course and user, just return that if found. (optional)
check_scorm_cloud	check_scorm_cloud=t	check the SCORMCloud API for existing registrations as well as the local Bright database (optional). This can be useful in test scenarios where Bright SCORMCloud crawler is not functioning, and it is desirable not to create a lot of duplicate registrations. Typically not used in production.
fname	fname=bret	Can be used to set the first name in the SCORMCloud registration.
lname	lname=weinraub	Can be used to set the last name in the SCORMCloud registration.

5.6.4.2. HTTP Codes

Code	Description
201	Success; item created
401	If you do not specify a valid sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP error 401 (unauthorized).
403	In some cases an additional error message is returned (see below).
404	You provided a course_guid that can't be found for this access method, or none at all. If you are using the create (and not gcreate alias), make sure you are posting the data correctly.
500	If you specify a user_email that is not valid, or a valid course_guid, you will receive a 500 server error.

In case of errors accessing the SCORMCloud API, a message including the error is returned (error code 403):

{
"error_code":"4",
"error_message":"The maximum number of registrations has been reached.",
"error_url":"https://cloud.scorm.com/api?email=..."
}

Please note if you are using JSONP, since there are limited facillities to capture errors via JSONP, we will return error code 200, with the error block above. Otherwise you might find it difficult to correctly handle this error.

5.6.4.3. Example

For a successful request returned will be an XML or JSON document of the SCORMCloud registration. Note this example is using the gcreate alias (using an HTTP get).

curl -w "%{http_code}" 
'https://[BRIGHT URL]/bright/api/v2/registration/gcreate.json?
api_key=2a84a6ddb229c13bc945874b69fab8ba&
learner_id=bret@aura-software.com&
course_guid=16-4fbd9ea698bce&
sc_app_id=XXXYYYYZZZ&
sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N&
dont_duplicate=t'
{
 "attempts"=>2,
 "complete"=>"complete",
 "course_result"=>'<?xml version="1.0" encoding=...?> <rsp>...</rsp>',
 "crawl_error_msg"=>nil,
 "crawl_status"=>"success",
 "crawl_type"=>"course",
 "created_at"=>"2012-12-21T08:39:12Z",
 "full_result"=>nil,
 "id"=>5336,
 "last_crawled_at"=>"2012-12-12T16:33:33Z",
 "learner_id"=>"bret@aura-software.com",
 "number_of_crawl_errors"=>0,
 "provider_completed_at"=>nil,
 "course_guid"=>"20-NSFoundationPostTrainingQuiz",
 "provider_created_at"=>"2012-12-12T16:32:04Z",
 "deleted"=>nil,
 "provider_errcode"=>nil,
 "provider_error_message"=>nil,
 "provider_accessed_at"=>nil,
 "registration_guid"=>"79c0dd35-139-048258-16e-9a1561b0a85d",
 "score"=>99.2,
 "course_provider_id"=>10,
 "course_id"=>509,
 "success"=>"succeeded",
 "totaltime"=>100.0,
 "updated_at"=>"2012-12-21T08:39:12Z"
}

5.6.5. Method: launch_url

The launch_url method is used to a get a unique, transient URL for course launch in direct response to a course launch event. Note, these cannot be cached, as they will expire.

5.6.5.1. HTTP Model

Verb	Form
GET	(http|https)://BRIGHT_URL/bright/api/v2/registration/[registration_guid]/launch_url.[format=xml|json|csv]?params...

5.6.5.2. parameters

Parameter	Example	Notes
__access method__	One of: api_key=xxxxxxxxxx [an api key created previously] sc_app_id=XXXXXXXXX&sc_secret_key=YYYYYYYYYYY [a valid SCORMCloud app ID/secret key pair] realm_guid=XXXXXXXXX&realm_secret_key=YYYYYYYYYY [a valid Bright Realm GUID/secret key pair]	see [Access Modes](#access-modes)
launching	launching=?launching=1	Deprecated. Historically, caused the creation of a launchHistory record in Bright; which is now deprecated
review	review=?review=1	Specifies the course will be launched in review mode and progress will not be tracked
redirect_url	redirect_url=?redirect_url=[uri encodeed URL]	When the user exits the course, the browser window will redirect to this URL
tags	tags=?tags=[uri encoded list of course tags]	Feature included for backward compatibility with the SCORMCloud plugin for WordPress. When a course was launched from a page/post, the course was auto-tagged with the page category.

5.6.5.3. HTTP Codes

Code	Description
200	Success; items returned
401	If you do not specify a valid api_key, sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP
500	An illegal request, such as a malformed argument

5.6.5.4. Example

5.6.5.5. Return Data

5.7. StoredQuery

5.7.1. Method: initialize

Initialize is generally not necessary, but can be used in fresh installs of Bright Server to initialize the stored queries with a query_scope of 'bright'.

5.7.1.1. HTTP Model

Verb	Form
GET	(http|https)://BRIGHT_URL/bright/api/v2/initialize[.format]

5.7.1.2. parameters

Parameter	Example	Notes
__access method__	One of: api_key=xxxxxxxxxx [an api key created previously] sc_app_id=XXXXXXXXX&sc_secret_key=YYYYYYYYYYY [a valid SCORMCloud app ID/secret key pair] realm_guid=XXXXXXXXX&realm_secret_key=YYYYYYYYYY [a valid Bright Realm GUID/secret key pair]	see [Access Modes](#access-modes)

5.7.1.3. HTTP Codes

Code	Description
200	Success; items returned
401	If you do not specify a valid api_key, sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP 401

5.7.1.4. Example

5.7.1.5. Return Data

5.7.2. Method: run

5.7.2.1. HTTP Model

Verb	Form
GET	(http|https)://BRIGHT_URL/bright/api/v2/run[.format]?name=[query-name]&...

5.7.2.2. parameters

Parameter	Example	Notes
__access method__	One of: api_key=xxxxxxxxxx [an api key created previously] sc_app_id=XXXXXXXXX&sc_secret_key=YYYYYYYYYYY [a valid SCORMCloud app ID/secret key pair] realm_guid=XXXXXXXXX&realm_secret_key=YYYYYYYYYY [a valid Bright Realm GUID/secret key pair]	see [Access Modes](#access-modes)
name	name=myStoredQuery	this is the query to run. Note for "builtin" queries, these are available for all realms and you will need to set query_scope=bright
query_scope	query_scope=bright	when set to "bright", the indication is this stored query is generic, not custom to your course provider or realm
format	format=csv|json|xml	defines the format the data should be returned as. Will set the content type of the response

5.7.2.3. HTTP Codes

Code	Description
200	Success; items returned
401	If you do not specify a valid api_key, sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP 401
404	A typical result when no stored query is found for your name= paramter
500	An illegal request, such as a malformed argument

5.7.2.4. Example

5.7.2.5. Return Data

5.8. Template

5.8.1. Method: index

5.8.1.1. HTTP Model

Verb	Form
GET	(http|https)://BRIGHT_URL/bright/api/v2/template[.format]?param1=value1&...

5.8.1.2. parameters

Parameter	Example	Notes
__access method__	One of: api_key=xxxxxxxxxx [an api key created previously] realm_guid=XXXXXXXXX&realm_secret_key=YYYYYYYYYY [a valid Bright Realm GUID/secret key pair]	see [Access Modes](#access-modes)
name	name=My Template	filter results to just this name.
markup	markup=handlebars	filter results to just this markup.
mimetype	mimetype=text/html	filter results to just this mimetype.

5.8.1.3. HTTP Codes

Code	Description
200	Success; items returned
401	If you do not specify a valid api_key, sc_app_id/sc_secret_key or realm_guid/realm_secret_key, you will receive HTTP 401
500	An illegal request, such as a malformed argument

5.8.1.4. Example

5.8.1.5. Return Data

5.8.2. Method: create

5.8.2.1. Parameters

5.8.2.2. HTTP Codes

5.8.2.3. Example

5.8.3. Method: update (gupdate)

5.8.3.1. Parameters

5.8.3.2. HTTP Codes

5.8.3.3. Example

6. Debugging Errors

The Bright API, if it's not happy with its input, isn't going to give you that much information as to why. It doesn't produce error messages other than HTTP codes. This is primarily for security reasons. Since we listen on public ports, we don't want people probing the api, and using the error messages as a guide to on how to gain access.

From curl, if you put an invalid response, you'll get no data back:

curl 'https://[BRIGHT URL]/bright/api/v2/course.json?sc_app_id=RQIBAXU49I
&sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N'

We asked for a jsonc format, which of course doesn't exist.

The only information you will get is an HTTP error code, in this case 406, 'Not Acceptable'.

6.1. Fetching HTTP Error Codes from a GET Request

You can see the HTTP response code for a GET request in curl with the -I flag:

curl 'https://[BRIGHT URL]/bright/api/v2/course.json?
sc_app_id=RQIBAXU49I&
sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N' -I
 HTTP/1.1 406 Not Acceptable
 Content-Type: text/html; charset=utf-8
 X-Ua-Compatible: IE=Edge,chrome=1
 Cache-Control: no-cache
 X-Request-Id: d4da4e1010b84640e1657b731ada79a3
 X-Runtime: 0.004287
 Date: Fri, 07 Dec 2012 23:04:10 GMT
 X-Rack-Cache: miss
 Content-Length: 0
 Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-04-20)
 Connection: Keep-Alive

You will also get no data from a request that matches no data. But in this case, the HTTP code will be 200

curl 'https://[BRIGHT URL]/bright/api/v2/course.json?sc_app_id=RQIBAXU49I\
&sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N&title=nosuchcourse'

[]

curl 'https://[BRIGHT URL]/bright/api/v2/course.json?sc_app_id=RQIBAXU49I
&sc_secret_key=nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N&title=nosuchcourse' -I
  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  X-Ua-Compatible: IE=Edge,chrome=1
  Etag: "d751713988987e9331980363e24189ce"
  Cache-Control: max-age=0, private, must-revalidate
  X-Request-Id: 73a4966a2a62ca4e70316f6a68645b51
  X-Runtime: 0.006220
  Date: Fri, 07 Dec 2012 23:06:40 GMT
  X-Rack-Cache: miss
  Content-Length: 0
  Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-04-20)
  Connection: Keep-Alive

6.2. Fetching HTTP Error Codes from a POST Request

Since we use a RESTful API, some operations require a POST HTTP verb. For whatever reason, the -I flag in curl will not show you the HTTP return code for a POST.

Instead use the following:

curl -w "%{http_code}"  -d 'sc_app_id=RQIBAXU49Ix&sc_secret_key=\
nCwrTDSy1MzaeyhN0TFfi3uH3huzlu6CNmyHUG5N&user_email=newuser@aura-software.com' \
https://[BRIGHT URL]/bright/api/v2/api_key

-w %{http_code} is the key part of that.

6.3. Debugging Authentication Errors

If you receive a 401 code from the API, the server itself has recorded the authentication error in the server log. If you are completely stumped, this is the place to look.

An error like this should exists:

Processing by ScormCloudCourseController#index as JSON
  Parameters: {"api_key"=>"bogus!", "course_guid"=>"course1"}
  �[1m�[36mApiKey Load (0.4ms)�[0m  �[1mSELECT "api_keys".* FROM 
  "api_keys" WHERE "api_keys"."access_token" = 'bogus!' LIMIT 1�[0m
Unauthorized: api token not found
Filter chain halted as :restrict_access rendered or redirected
Completed 401 Unauthorized in 2ms (ActiveRecord: 0.4ms)

Definitely give us a shout if you can't get an API call to work at support@aura-software.com.