This guide is for course providers who want another system, such as their own website or an internal tool, to work with their Cademy account through the Cademy API. It explains how to create an API key, store it safely, check that it is being used, and revoke it.
The Cademy API lets software read information from your Cademy account, and add orders to it, without anyone signing in. An API key is a secret code that the software sends with every request to show that it is allowed to use your account. Treat an API key like a password.
Connecting a system to the Cademy API is a technical task, done by a developer or by the supplier of the other system. This guide covers the part that happens in Cademy: the key.
What an API key gives access to
A system that sends a valid API key can do the following in your Cademy account:
Search your courses.
Read the details of one of your courses.
Read the dates of one of your courses. Only dates that have not started yet are returned.
Read your reviews.
Create an order for one or more of your courses. If the customer on the order is not already one of your contacts, Cademy adds them.
Read and change the settings that connect a WordPress website to your account, including the address of the website and the path of its course pages. This is how Cademy for WordPress uses its key.
Every key gives the same access. You cannot limit a key to certain courses, or to reading only. A key works only for the Cademy account it was created in.
The first five are described in the Cademy API documentation, which lists each request and the information it returns. It is written for developers.
The API answers requests that your system sends to Cademy. To have Cademy send events to another system instead, use webhooks. See Webhooks: Send Cademy Events to Other Systems.
Before you start
Check these points before you create a key:
Plan: your Cademy account needs the API keys feature. It is included in the Teams plan. If you are on an Enterprise plan, check that your agreement includes API keys. To compare plans, see Understand Cademy Plans, Limits and Fees.
Role: you need the System Admin role. Course Owners and Facilitators do not see API Keys in Settings.
Purpose: know which system will use the key, so that you can name the key after it.
To connect a WordPress website, do not use this guide. Create the key on the Cademy for WordPress page instead. See Cademy for WordPress: Embed Courses on Your Website.
Open the API Keys page
You create, check and revoke keys on one page in Settings.
Sign in to the Cademy admin dashboard as a System Admin.
In the main menu, select Settings.
Under Tools, select API Keys.
The API Keys page opens. At the top are the API Documentation link and the Create New API Key button. Below them is a table of the keys on your account. Until a key exists, the table shows “No API keys found. Create your first API key to get started.”
The table has these columns, from left to right:
NAME: the name given to the key when it was created.
KEY: the first five characters of the key, followed by dots. The rest of the key is never shown in the table.
CREATED: the date and time the key was created.
LAST USED: the date and time Cademy last accepted the key on a request, or “Never used”.
ACTIONS: one icon. Its tooltip reads Revoke API Key.
The table lists every key on your account that has not been revoked, whoever created it. Keys created on the Cademy for WordPress page are in the table too. Their names start with “WordPress”.
If your account does not have the API keys feature, the page shows a Cademy Teams Feature badge, and the rest of the page is faded and cannot be used. Select the badge to open Billing & Usage, where you can change your plan.
Create an API key
Create a separate key for each system that connects to Cademy. You can then revoke the key of one system without stopping the others, and LAST USED shows which systems are active.
Important: The full key is shown only once, in the window that opens after you select Create in step 3. Cademy does not store the key in a form that can be shown again. That window closes when you select I've Saved My API Key or the cross icon, press Escape, or click outside the window. Copy the key before you do any of these. If the window closes first, revoke that key and create another one.
On the API Keys page, select Create New API Key. The Create New API Key window opens.
In API Key Name, enter a name that says what the key is for, for example “Website course list”. The page has no option to change the name later. If you leave the name empty, Cademy shows “Please enter a name for the API key” and does not create the key.
Select Create. A second window opens, titled API Key "Website course list" Created. It shows the full key under a warning titled Important. Keep this window open until you have copied the key.
Select Copy Key to Clipboard. Cademy confirms with “API key copied to clipboard”.
Paste the key into the place where you will keep it. See “Store and use the key safely” below.
Select I've Saved My API Key. The window closes. The key is in the table with “Never used” under LAST USED.
A key is 64 characters long and contains only the digits 0 to 9 and the letters a to f. Use this to check that the whole key was copied.
Store and use the key safely
Until a key is revoked, anyone who has it can read your course and review information, create orders in your account, and change the settings of your WordPress connection.
Keep the key in a password manager, or in the secret storage of the system that uses it.
Use the key only in software that runs on a server. Do not put it in web page code, a mobile app or any other place that other people can inspect.
Do not paste the key into a support conversation. To identify a key to someone, give its name and the five characters in the KEY column.
If a key has been seen by someone who should not have it, revoke it and create a new one.
Get the key to the system that uses it
The key has to be entered in the system that connects to Cademy. Choose the route that shows the key to the fewest people:
Enter the key in that system yourself.
If the person who builds the connection has the System Admin role on your Cademy account, they can create the key themselves on the API Keys page.
If you have to hand the key to another person, use a tool made for sharing passwords, such as a shared entry in a password manager. Do not send the key by email or chat.
How a system sends the key
Give your developer the link to the Cademy API documentation. Every request to the API must include a header named Authorization whose value is the key and nothing else:
Authorization: YOUR_API_KEY
Replace YOUR_API_KEY with the key. Do not add a word such as “Bearer” before it. If the header contains anything other than the key, Cademy refuses the request.
Check that a key is being used
Each time Cademy accepts a key on a request, it records the time against that key. To see it, open the API Keys page and read the LAST USED column:
“Never used”: Cademy has not accepted a request with this key.
A date and time: the most recent request that Cademy accepted with this key, in the time zone of your browser.
If the page was already open, reload it to see the latest time.
When Cademy refuses a key, the API replies with status 401 and one of these titles. Your developer sees them in the reply to the request:
“API Key is missing”: the request has no
Authorizationheader.“API Key is invalid”: the value of the
Authorizationheader is not a key that Cademy accepts. Check that the whole key was copied, that nothing was added before or after it, and that the key has not been revoked.
Revoke an API key
Revoke a key when the system that used it is no longer in use, when someone who knows the key should no longer have access, or when the key has been seen by someone who should not have it. Revoking cannot be undone.
Revoking a key that was created on the Cademy for WordPress page disconnects that website from Cademy. The names of these keys start with “WordPress”.
Revoke the keys you no longer need before your account moves to a plan without the API keys feature. A plan change does not revoke keys, and the API Keys page cannot be used without the feature.
On the API Keys page, find the key by its name and by the five characters in the KEY column.
In the ACTIONS column of that row, select the Revoke API Key icon. A window opens. Its title is Revoke API Key: followed by the name of the key.
Read the warning, then select Revoke. To keep the key, select Cancel.
Cademy confirms with “API key revoked successfully” and removes the key from the table. From then on, Cademy refuses every request that uses the key, with the title “API Key is invalid”. A revoked key cannot be restored.
Replace a key without interrupting a system
A key cannot be changed or shown again, so replacing a key means creating a new one and revoking the old one. Both keys work until you revoke the old one.
Create a new key. Give it a name that tells it apart from the old key.
Put the new key into the system that connects to Cademy.
Reload the API Keys page and check that LAST USED for the new key shows a recent time.
Revoke the old key.
Frequently asked questions
I closed the window before copying the key. Can I see the key again?
No. The full key is shown only in the window that opens when the key is created. Revoke that key and create a new one.
Can I rename an API key?
No. The API Keys page has no option to rename a key. To use a different name, create a new key with that name, put it into your system, then revoke the old key.
How many API keys can I create?
The API Keys page does not limit the number of keys. Create one for each system that connects to Cademy, and revoke the keys that are no longer used.
What happens to a key when the person who created it leaves the team?
The key keeps working. A key belongs to your Cademy account, not to the person who created it, so removing that person from your team does not revoke it. If they know the key, revoke it and create a new one.
Why does LAST USED still show “Never used”?
Cademy records a time only when it accepts the key on a request. Reload the page first. If it still shows “Never used”, either the system has not sent a request with this key, or Cademy refused its requests. Ask your developer which reply the API returned.