Moodle web services are designed for external systems to call Moodle APIs. Moodle provides a full web service framework for external integrations.

---

Step 1: Login as Moodle Admin

Open Moodle admin panel:

https://www.yourdomain.xyz

Login with admin account.

---

Step 2: Enable Web Services

Go to:

Site administration > Advanced features

Enable:

Enable web services

Save changes.

---

Step 3: Enable REST Protocol

Go to:

Site administration > Server > Web services > Manage protocols

Enable:

REST protocol

REST is needed because your Laravel project will call Moodle like this:

/webservice/rest/server.php

---

Step 4: Create Custom External Service

Go to:

Site administration > Server > Web services > External services

Click:

Add new custom service

Fill:

Name: DS Enroll Moodle Integration
Short name: ds_enroll_moodle_integration
Enabled: Yes
Authorised users only: Yes

Save it.

---

Step 5: Add Required Moodle API Functions

Open your created service:

DS Enroll Moodle Integration

Click:

Functions > Add functions

Add these functions:

core_user_get_users_by_field
core_user_create_users
core_cohort_add_cohort_members

Purpose:

Function	Use
core_user_get_users_by_field	Find Moodle user by email
core_user_create_users	Create Moodle user if email does not exist
core_cohort_add_cohort_members	Add Moodle user to OneMembership cohort

---

Step 6: Create Moodle API User

Create a dedicated user for API integration.

Go to:

Site administration > Users > Accounts > Add a new user

Example:

Username: ds-enroll-api
Email: useremail@gmail.xyz
First name: DS Enroll
Last name: API
Authentication method: Manual accounts

Set a strong password.

For quick testing, assign this user a role with enough permission, such as Manager. Later, you can create a restricted custom role.

---

Step 7: Add User to External Service

Go to:

Site administration > Server > Web services > External services

Open:

DS Enroll Moodle Integration

Click:

Authorised users

Add this user:

ds-enroll-api

---

Step 8: Create Moodle Token

Go to:

Site administration > Server > Web services > Manage tokens

Click:

Add

Select:

User: ds-enroll-api
Service: DS Enroll Moodle Integration

Optional but recommended:

IP restriction: your ds-enroll-ms server public IP
Valid until: optional expiry date

Click:

Save changes

Copy the token immediately.

Moodle documentation says tokens can be created from Site administration > Server > Web services > Manage tokens, then selecting the user and service. (Moodle Docs) Moodle also notes that web service tokens are read-once, so if you lose it, you need to create a new one. (Moodle Docs)

---

Step 9: Add Token in ds-enroll-ms .env

In your Laravel project:

MOODLE_BASE_URL=https://www.yourdomain.xyz
MOODLE_TOKEN=paste_token_here
MOODLE_ONEMEMBERSHIP_COHORT_ID=123

Never put this token in:

Blade file
JavaScript
GitHub
API response
Frontend code
Log file

---

Step 10: Test Token with Curl

Test user lookup by email:

curl -X POST "https://www.yourdomain.xyz/webservice/rest/server.php" \
  -d "wstoken=YOUR_MOODLE_TOKEN" \
  -d "wsfunction=core_user_get_users_by_field" \
  -d "moodlewsrestformat=json" \
  -d "field=email" \
  -d "values[0]=test@example.com"

If token is working and user does not exist, response may be:

[]

If token/service/permission is wrong, you may get:

{
  "exception": "webservice_access_exception",
  "errorcode": "accessexception",
  "message": "Access control exception"
}

---

Step 11: Test Cohort Add API

After you get Moodle user ID, test:

curl -X POST "https://www.yourdomain.xyz/webservice/rest/server.php" \
  -d "wstoken=YOUR_MOODLE_TOKEN" \
  -d "wsfunction=core_cohort_add_cohort_members" \
  -d "moodlewsrestformat=json" \
  -d "members[0][cohorttype][type]=id" \
  -d "members[0][cohorttype][value]=123" \
  -d "members[0][usertype][type]=id" \
  -d "members[0][usertype][value]=MOODLE_USER_ID"

Here:

123 = OneMembership cohort ID
MOODLE_USER_ID = Moodle numeric user ID

---

Required Checklist

Before giving token to Claude/code, confirm these are done:

[ ] Web services enabled
[ ] REST protocol enabled
[ ] Custom external service created
[ ] Required functions added
[ ] API user created
[ ] API user added as authorised user
[ ] Token generated
[ ] Token copied safely
[ ] Token added in ds-enroll-ms .env
[ ] Curl test successful

Final .env values for Claude/code:

MOODLE_BASE_URL=https://www.yourdomain.xyz
MOODLE_TOKEN=your_generated_token
MOODLE_ONEMEMBERSHIP_COHORT_ID=123