Tahoe Registration API v2

API Endpoints available for registering users on Tahoe from a third-party system.

Use these to collect initial registration information from users through an external system (including information that Tahoe doesn’t need like instance: title, department, company, etc) and then send the relevant information over to Tahoe to start the learner’s registration process there. 

Important notes:

  • Registration is the process of signing up for an account on an Open edX site. It requires at least an email, name, username, password, and acceptance of TOU/Privacy Policy. It does not enroll the user in any courses.
  • Enrollment is the process of enrolling a registered user in one or more courses.
  • In this doc, you will see references to Token <insert token here>. If you are a Tahoe site admin, please contact support@appsembler.com to request a unique auth token for your site.

User Registration / Creation

Endpoint: https://<yoursitename>.tahoe.appsembler.com/tahoe/api/v2/registrations/ 
Request Method: POST

Required Parameters

Name Type Description
username string The user’s Tahoe username. This is a unique value in the Tahoe system, and cannot be changed once set.
email string The user’s email address. This is also a unique value in the Tahoe system, but can be updated by the user from their profile management page.
name string The user’s full name.

Optional Parameters

Name Type Description
password string Set the user’s password. This is useful if you’re gathering the password at registration time in another system, and want to pass that value along to Tahoe. If you wish to skip the automatic account activation email, you can do so by setting the send_activation_email parameter to False. If you do not specify a password, no activation email is sent. Instead, the user is sent a password-reset email, so they can set their own secure password.
send_activation_email boolean Note: If you do not provide a password, this value is automatically set to False and cannot be overridden. In that case, the user receives a password-reset email, so they can set their own secure password.If you provide a password, this defaults to True, but can be overridden to False. If you set it to False, you are responsible for verifying the accuracy of the email address. You are confirming that you have already done so via another system, in accordance with best practices for account creation.

Return

Response Code Description
HttpResponse: 200

User registration successful. Response body contains the user_id for use in future API calls 

  • v2: trailing space removed in response (e.g. {“user_id ”: 9} → {“user_id”: 9})
HttpResponse: 400 Invalid request. May be missing required parameters, or parameters of the wrong type.
HttpResponse: 409

An account with the given username or email address already exists.

  • v2: specific response for when given username, email address, or both username and email address already exists (see responses in Examples below)

Examples

This example uses the curl command to submit the POST, but you can use your tool or library of choice.

curl -v -X POST \   
https://<yoursitename>.tahoe.appsembler.com/tahoe/api/v2/registrations/ \   
-H 'Authorization: Token <insert token here>' \   
-H 'Content-Type: application/json' \   
-H 'cache-control: no-cache' \   
-d '{ 
"username": "auserton", 
"email": "alex.userton@example.com", 
"name": "Alex Userton" }'

HttpResponse: 409 for duplicate username only

{"user_message":"Username already exists",
 "invalid-params":["username"]}

HttpResponse: 409 for duplicate email only

{"user_message":"Email already exists",
 "invalid-params":["email"]}

HttpResponse: 409 for duplicate username and email

{"user_message": "Both email and username already exist", 
 "invalid-params": ["email", "username"]}

Related Articles