Turning on the API
The Grapevine API lets other websites and systems use your site’s courses: show them on your own website, enroll people from your HR system, or read results into a report. This article is the part a site administrator does. What a developer does with it is in the API reference.
It is in Site Admin, on the Integrations tab, in the API section. Only the site’s administrators see it, and only while signed in themselves — a key can never be used to make another key.
The Grapevine API is included in every paid plan. On a site without one, the section says so and the switch will not turn on. If there is no Integrations tab at all, the API has not been opened on your network yet — ask us.
Turning it on
- Tick Turn on the Grapevine API for this site.
- Under Websites allowed to use it, list each website that will show your courses, one per line, like
https://example.org. Your Grapevine site itself is always allowed. You can list up to 20. - Press Save.
While the API is off, every key is refused. Turning it off again takes effect at once, which makes the switch the quickest way to stop everything if you ever need to.
Two switches worth reading twice
Turning the API on does not let any key change your courses or manage your people. Each of those takes a switch of its own, off until you tick it:
- Let other systems manage courses — lets a key create, change and delete your courses, including courses people are taking. Lessons a learner has already opened can never be changed this way.
- Let other systems manage people — lets a key add and remove people, give them roles (Site Admin included), and record and correct results.
Tick them only when a system you trust needs them, and only for as long as it does.
Keys
Every website or system that uses the API needs a key. Choose Create a key, say What is it for? — a name you will recognize later, like “Our website” or “HR system” — and pick its Kind:
| Kind | For | What it can do |
|---|---|---|
| Publishable | A web page | Read the public catalog only. Safe to put in a page, and you can see it again here at any time. |
| Secret | A server | Everything: it reads it all, and changes whatever the switches above allow. Never put it in a web page. |
| Restricted | A server | Only what you tick under What it may do. |
A restricted key is how you narrow a key to one job: a system that only reads results gets results:read and nothing else, so a leak of that key cannot do anything more. Each choice under What it may do says in plain words what it allows.
A secret or restricted key is shown once, when you create it. Copy it then and keep it on a server. If one is ever sent from a web page, Grapevine refuses it — revoke it and make a new one.
Revoking a key
Each key shows when it was last used. Revoke stops it at once: anything using it stops working, and it cannot be undone. A key cannot be changed after it is made, so to give a system more or less, create a new key and revoke the old one.
Webhooks
In the same section, Webhooks let Grapevine tell another system when something happens — a learner finishes a lesson or a course, say — by sending it to an address you give. Your developer sets these up; the reference explains them.
Next
- To put your courses on your own website, see Putting courses on your website.
- To open your courses from Moodle or another LMS, see Connecting your LMS.
- For developers, the API reference lists every call, and each one can be tried there against a sample site.