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:
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'
Read Only API Keys
What Are Read-Only API Keys?
Read-only API keys are designed to permit only "Read" or "Get" operations. This feature allows you to enable Integration Partners to gather data from the Skilljar API without the risk of altering or modifying your learning site or data.
By granting read-only API keys, you can securely allow integration partners to access your data without the risk of them modifying any information and ensure that your downstream tools and applications have the precise level of access they need to your API data, without exposing your organization to unnecessary risks.
Implementation Details
- Validation for Every API Operation: When a call is made, the system checks for key permission (new boolean) and denies any POST, PUT, UPDATE, DELETE requests if the key is read-only.
-
Dashboard Setting: This can be defined on the dashboard when creating API keys and cannot be edited once the key is saved.
- For more details and to create an API key, visit Skilljar API Key Creation.
Important Notes about Read-Only Keys
Some integrations may require write access (e.g., to create a webhook), so if a partner has already built an integration with Skilljar, ensure they are okay with only using a Read-Only key.
Once a read-only key has been generated, it is not possible to “edit” that key to be able to write. If you want to provide a full-access key to an integration partner, you can delete the “Read-Only” key and create a new normal key to pass securely to your integration partner.