Quick Menu

API Access

Tutor enables the API by default! 🎉 You can view the API documentation on your instance at https://your-edx/api-docs, for example https://edx.ektu.kz/api-docs/

This page explains how to generate an OAuth token to access the API endpoints using Authorization Bearer on Open edX. This method demonstrates one of the several ways of accessing the API.

Create an API User (optional)

This step is optional if you already have a user that you want to use for API access. We haven't tested it, but you can probably give specific permissions to a non-superuser account. There is some security risk to giving your API user admin rights.

tutor local createuser --staff --superuser api-user api@example.com

Create the Application API

The first step is to create an OAuth API application.

  1. Log into your LMS admin panel at https://your-edx/admin.

  2. Navigate to OAuth Applications at https://your-edx/admin/oauth2_provider/application/

  3. Press the Add Appliacation button.

    • Client id: <default>
    • User: Find the user to grant API access
    • Client type: confidential
    • Authorization grant: client credentials
    • Client secret: <default>
    • Name: Enter name of the API application

  4. Save the OAuth application.

Create an Access Token

Next, you will create an access token for the API user to access the API application

  1. Navigate to Access tokens at https://your-edx/admin/oauth2_provider/accesstoken/.

  2. Press the Add Access Token + button.

    • User: Select the user that you gave access to in the OAuth application
    • Source refresh token: Leave blank
    • Token: Enter a random CodeIgniter Encryption Key from RandomKeygen
    • Application: Select the OAuth application
    • Expires: Set the expiration date for the access token

  3. Save to access token

Testing and Using the API

Tip: Use the API Docs page to generate the API URL.

Using API-DOCS Test site

  1. First, open the API docs page (https://your-edx/api-docs) and log in using your API user with admin rights.

  2. Find an API endpoint to test, such as a GET request for /course_modes/v1/courses/{course_id}/

    • Press the Try it out button
    • Enter a course_id
    • Press the Execute button
    • Verify that that HTTP response code is 200 and that the response body contains valid data.

    Take note of the Request URL. You will need to use this URL when using curl because it escapes the characters in the course ID

Using curl

You can use curl to access the API remotely using this syntax:

 curl "<URL>" -H "Authorization: Bearer <ACCESS_TOKEN>"
  1. URL: Use the Request URL from the API-DOC test
  2. ACCESS_TOKEN: Use the access token for your API user

For the /enrollment/v1/course/{course_id} example above:

curl "https://edx.ektu.kz/api/course_modes/v1/courses/course-v1%3ACET%2BGW_01%2B2021_2022_FA/" -H "Authorization: Bearer super-secret-key"

Valid output: This response verifies that the bearer authorization is configured correctly.

[{"course_id":"course-v1:CET+GW_01+2021_2022_FA","mode_slug":"honor","mode_display_name":"Сертификат","min_price":0,"currency":"usd","expiration_datetime":null,"expiration_datetime_is_explicit":false,"description":null,"sku":null,"bulk_sku":null}]

Error encountered: (problem access token or credentials) 

# Invalid token
curl "https://edx.ektu.kz/api/course_modes/v1/courses/course-v1%3ACET%2BGW_01%2B2021_2022_FA/" -H "Authorization: Bearer asdfasdfasfd"
{"error_code":"token_nonexistent","developer_message":"The provided access token does not match any valid tokens."}

# No credentials provided
curl "https://edx.ektu.kz/api/course_modes/v1/courses/course-v1%3ACET%2BGW_01%2B2021_2022_FA/"
{"detail":"Authentication credentials were not provided."}

References