Quickstart Guide

The following quickstart guide will walk through how to access and make a call to the Teachable API.

If you are already comfortable with how to make requests to the API, you can jump ahead to Authentication and reviewing all available endpoints in our reference documentation.

1. Signing up for an account

To use the Teachable API, you must have a Teachable account on the Growth plan or higher. Sign up here for a Teachable account.

2. Getting your API Key

Next, you will need to get your API keys. Your API keys are how you authenticate your requests to the API.

To get your API keys:

1. Navigate to the Settings > API tab of your Teachable school admin.
2. Click the Create API Key button.
3. In the popup window, enter a Name for your API Key.
4. Click Create.

Once you have your API key, you will need to include it in the header of request calls you make to the API.

Learn more about Authentication.

2.1. Selecting permissions

API v2 keys carry scopes — permissions that define exactly what the key can do. You choose them when you create the key.

Permissions are organized by resource — Users, Courses, Enrollments, Transactions, and so on. Expand a resource to select individual operations, or use Select by operation at the top to apply an operation across every resource at once:

• Read — view all data
• Create — add new records
• Update — modify records
• Delete — remove records

Select only what your integration needs. A key limited to reading course and enrollment data cannot modify or delete anything, so if it's ever exposed, the damage is bounded by what you granted.

Example — a reporting integration. An integration that generates a report of course enrollments needs to read courses and enrollments, and nothing else. Expand Courses and select Read, expand Enrollments and select Read, and leave every other resource clear. The resulting key can read those two resources and will be refused on everything else — it cannot create users, issue refunds, or delete a course, no matter what the integration's code asks for.

🚧

Selecting nothing grants everything

If you create a key without selecting any permissions, it is created with all permissions. Always select the specific permissions your integration needs.

3. Understanding scopes

Each scope is written as resource:action — for example courses:read or users:create. The permissions you selected when creating your key map directly onto these: expanding Courses and selecting Read grants courses:read.

Scoping each key to a single integration's needs means:

• A leaked key exposes less. If a key is committed to a public repository or leaks through a third-party tool, the damage is bounded by that key's permissions rather than by everything your school can do.
• Mistakes are contained. A key without delete permissions cannot delete anything, however wrong the code using it is.
• Access is auditable. A key's permissions tell you what an integration can reach without reading its source.
• Revoking is surgical. You can remove one permission from one key instead of rotating a key that everything depends on.4.Making a Request

Issue a separate key per integration rather than sharing one broadly scoped key — that's what makes each of the above true in practice.

📘

API v1 keys do not use scopes. A v1 key can reach every v1 endpoint your plan allows. Scopes apply to API v2.

3.1. When a permission is missing

If a request requires a scope your key doesn't have, the API returns 403 Forbidden and names what was missing:

JSON

{
  "error_code": "insufficient_scopes",
  "message": "Missing required scopes: courses:update"
}

Add the missing permission to the key from Settings > API, or use a key that already has it.

🚧

Permission availability during Beta

While API v2 is in Beta, the endpoints available to your school may be limited. If you receive 403 insufficient_scopes for a permission your key has, your school may not yet have access to that part of the API — contact support to request access. Permission changes can take up to five minutes to take effect.

4. Making a request

1. Select an endpoint you'd like to use.

You can view all available endpoints in our reference documentation. For example, you can use the /courses endpoint to fetch data on all courses in your school.

2. Choose a tool to make your request in.

Throughout our documentation, we write our requests in cURL—these cURL requests can be executed directly from your Terminal (Mac) or Command Prompt (Windows).

You can also choose to make your requests through various third-party graphical user interface (GUI) clients, such as Postman or Paw.

3. Format and make your request.

Your request will be composed of:

• A request method (GET, POST, PATCH, or DELETE). For example, if you selected the /courses endpoint, you would be using the GET request method.
• URL: The URL consists of the base URL (i.e., developers.teachable.com) and the specific endpoint you’re using. For example, the full request URL of the /v2/products/courses endpoint is https://developers.teachable.com/v2/products/courses.
• Header: This is where you include your API Key for authentication.

A sample request is formatted as follows:

curl --request GET \
     --url https://developers.teachable.com/v2/products/courses \
     --header 'apiKey: YOURKEYHERE'

Requires the courses:read scope.

4. Use parameters to specify your request.

Some endpoints have parameters that you can add to the request URL to specify your request. Some parameters are required (e.g., indicating a specific course ID when enrolling users into a course with the /enroll endpoint), while others are optional. The reference documentation will indicate when a parameter is required.

A sample request to the /v2/products/courses/{course_id} endpoint, including parameters (e.g., adding a course_id of 123), is formatted as follows:

curl --request GET \
     --url https://developers.teachable.com/v2/products/courses/123 \
     --header 'apiKey: YOURKEYHERE'

5. Next steps

Now that you know how to make a call to the Teachable API, you can review all available endpoints in our reference documentation to begin utilizing the API according to your business needs.

If you're building an integration that acts on behalf of an individual student rather than administering the school, see the OAuth QuickStart Guide. The End User API uses a different permission model: your app requests scopes and the student approves them.