Getting started with the Skilljar API

  • Updated

API Keys and Authentication

API Key

API keys are generated via the Skilljar Dashboard. If you are an admin on your account, you can generate an API Key from Organization settings > API Credentials page. Select the "Create a Key" button to generate a new API Key. You can use this API key to begin making a few basic API calls.

Skilljar's API endpoint is https://api.skilljar.com/v1

Authentication

API calls are authenticated via HTTP Basic Authentication. The API Key is the User, and the password is blank. For example, if your key is "sk-live-abcdeg", then all requests to our API endpoint should contain the HTTP Header:

Authorization: Basic c2stbGl2ZS1hYmNkZWc6

That is, where c2stbGl2ZS1hYmNkZWc6 is the base-64 encoded string sk-live-abcdeg: as per the HTTP Basic Auth spec. Most HTTP libraries will do this for you, so you don't have to worry about constructing and adding the header explicitly.

Alternatively, you can pass in API key in the user field:

--user "<api-key>"

Passing in the API Key this way does not require base-64 encoding.

First API call - Ping the API endpoint

You can test a basic call & response via making an HTTP GET request to our "ping" endpoint:

https://api.skilljar.com/v1/ping

A successfully authenticated request should return an empty 200 response.

You'll notice if you access the /ping endpoint in your browser (and paste in your API key in the username prompt), you'll see a full HTML page with the API response. All of our APIs are accessible in this way to facilitate debugging.

JSON

To communicate with our endpoint using JSON encoding, you will want to specify it the Accept: header in your HTTP request. This doesn't apply much to the /ping endpoint since there is an empty response, but will apply once you start making legitimate API calls:

Accept: application/json

API Resource Reference

There are a few main resources within the Skilljar API. REST-like manipulation of these resources allow you to manage users within the course platform, enroll users in courses, and receive event notifications from the platform.

Domain

This is the domain your courses are hosted on, e.g. courses.yoursite.com

User

A user is a student within the system.

Course

This is a course.

PublishedCourse

A course is published to a domain via a PublishedCourse object

DomainUser

A user has access to a domain via a DomainUser object

Enrollment

A user is enrolled in a PublishedCourse via an Enrollment object.

Webhook

You can be notified of events within the course platform via Webhook objects.

The Details - API Endpoint Reference

Now that you understand how to make an API call, and what the primary resources are within the system, it's time to browse the API Endpoint Reference. The reference lives on your API endpoint and is generated dynamically from the source code itself. It's always up-to-date with the latest details about the platform.

The article Common API Tasks outlines some common uses of the Skilljar API and gives examples of using the API to create users, enroll them in courses, add them to domains, etc. You can also use our Webhooks API to listen for events that happen within Skilljar.

Try it out!

  • Navigate to https://api.skilljar.com/docs/
  • To test a specific API call, click on the "Try it out!" button
  • You'll be prompted for your Username and Password
  • In the Username field, enter in the API Key obtained to the Skilljar Dashboard
  • Leave the Password field blank and click the "Sign In" button:

Screen_Shot_2019-12-09_at_3.47.22_PM.png

 

API Call Rate Limits

We enforce the below API rate limits to ensure the highest levels of API availability and reliability. 

  • Rate Limits are per Skilljar Organization (not per API key)
  • Rate limits are per call type
    • Modification and Removal rate limits are separate from each other
  • Rate Limit Volumes
    • Burst rates up to 600 API calls / minute
    • Hourly rate up to 5,000 API calls / hour
      • Note: API Call Rate Limits only apply to the External API endpoints found in our API documentation. SAML, OAuth, and OIDC calls do not use the same API endpoints.
      • Rate limit time frames reset depending on when the request is made. 
        • Example: For the hour limit - if one request is made at 12:00 and 4,999 requests are made at 12.59, further requests can’t be made until the first request expires at 1:00, an hour after it was made. At 1:00 a new request can now be made, but any further requests will receive throttle responses until the other 4,999 expire at 1:59.

Rate Limit Error response:

If you hit one of the rate limits, the API response body will include the following information (among the rest of the API response)

  • 'status_code': 429
  • 'reason': 'Too Many Requests'

Was this article helpful?

1 out of 2 found this helpful