iblai-api-management

Mirrored from iblai/vibe · skills/users/iblai-api-management/SKILL.md. This page is generated — edit it in the repository, not here.

Administer an organization from the API: manage Users, Groups, Roles, Policies, Teams, and Alerts for organization-level user and access administration.

Auth & conventions

Base URL: https://api.iblai.app
Header: Authorization: Api-Token $IBLAI_API_KEY on every request.
Path vars: {org} = $IBLAI_ORG (a.k.a. platform_key), {username} = $IBLAI_USERNAME.
Host: these endpoints live on the DM host under /api/core/…. The exception is edX user roles (list / promote-demote / bulk sync), which flip to the edX LMS/CMS host - see the Users > Roles (edX) entries below. The org field on those calls is the edX course-organization short name, not the ibl.ai org key - see the reference doc linked in ## Reference material.
Not connected yet? Run /iblai-api-login first to populate IBLAI_ORG, IBLAI_USERNAME, and IBLAI_API_KEY.

Reads

Users

GET …/core/platform/users/?platform_key={org}&platform_org={org}&query={q}&page={n}&page_size=10&return_policies=true — user list + policies.

Roles (edX)

GET https://studio.learn.iblai.app/api/ibl/users/manage/roles/?username={username} - list a user's edX roles (global + course + org). Identify the user with username, email, or user_id. Full role catalog (what each role key means, which need course/org) and endpoint detail in references/edx-roles-reference.md.

Groups

…/core/rbac/groups/

GET …/groups/?platform_key={org}&include_users=true[&name=&email=&owner=&username=&page=&page_size=] — list.
GET …/groups/{id}/ — detail.

Roles

…/core/rbac/roles/ (all calls include include_global_roles=true)

GET …/roles/?include_global_roles=true&platform_key={org}[&name=&page=&page_size=] — list.
GET …/roles/{id}/?include_global_roles=true&platform_key={org} — detail.

Policies

…/core/rbac/policies/

GET …/policies/?platform_key={org}&include_groups=true&include_users=true[&role_id=&group=&name=&username=&email=&page=&page_size=] — list.
GET …/policies/{id}/?platform_key={org} — detail.

Teams

…/core/user-groups/ plus team access (…/core/rbac/teams/access/)

GET …/user-groups/?platform_key={org}[&include_users=&name=&with_permissions=&page=&page_size=] — list.
GET …/user-groups/{id}/?platform_key={org} — detail.
GET …/core/rbac/teams/access/?platform_key={org}&usergroup_id={id} — list a team's access policies.

Writes

Users

Roles (edX)

POST https://studio.learn.iblai.app/api/ibl/users/manage/roles/ - promote/demote, i.e. assign or unassign one role:
```
{
  "username": "string (required)",
  "role": "e.g. org-instructor (required - see role catalog)",
  "course": "course id - required for course roles",
  "org": "edX course-org short name - required for org roles",
  "active": "boolean (optional, default true - true assigns, false removes)"
}
```
General roles (staff, support-staff, course-creator) take neither course nor org. course-creator is CMS-only (the LMS host rejects it with 400). Full role catalog - what each key means and its scope requirement - is in references/edx-roles-reference.md.
POST https://studio.learn.iblai.app/api/ibl/users/manage/roles/sync/ - bulk-replace a batch of role assignments for one user in a single atomic request (all entries validated first; all succeed or all roll back). Body and response shape, plus inactive-user and idempotency behavior, in the reference doc above.

POST …/core/users/platforms/ — activate/deactivate:

{
  "user_id": "number (required)",
  "platform_key": "string (required)",
  "active": "boolean (required)"
}

PUT …/core/platform/users/policies/ — set policies (array):

[
  {
    "user_id": "number (required)",
    "platform_key": "string (required)",
    "policies_to_set": "string[] (required, may be [])"
  }
]

Groups

…/core/rbac/groups/

POST …/groups/ — create:

{
  "name": "string (required)",
  "platform_key": "string (required)",
  "description": "string",
  "users": "number[]"
}

PUT …/groups/{id}/ — update (same shape).
DELETE …/groups/{id}/?platform_key={org} — delete. Destructive — confirm with the user first.

Roles

…/core/rbac/roles/ (all calls include include_global_roles=true)

POST …/roles/?include_global_roles=true — create:
```
{
  "name": "string (required)",
  "platform_key": "string (required)",
  "actions": "string[] (RBAC action strings, e.g. Ibl.Mentor/Mentors/read)",
  "data_actions": "string[]"
}
```
The permission list is actions (+ optional data_actions), not permissions. See /iblai-api-rbac for the full role/policy model (action namespaces, resource paths).
PUT / PATCH …/roles/{id}/?include_global_roles=true — update (same shape).
DELETE …/roles/{id}/?include_global_roles=true&platform_key={org} — delete. Destructive — confirm with the user first.

Policies

…/core/rbac/policies/

POST …/policies/ — create:

{
  "name": "string (required)",
  "platform_key": "string (required)",
  "role": "number role id (required)",
  "resources": "string[]",
  "users": "number[]",
  "groups": "number[]"
}

PUT / PATCH …/policies/{id}/ — update (same shape).
DELETE …/policies/{id}/?platform_key={org} — delete. Destructive — confirm with the user first.

Teams

…/core/user-groups/ plus team access (…/core/rbac/teams/access/)

POST …/user-groups/ — create:

{
  "name": "string (required)",
  "platform_key": "string (required)",
  "description": "string",
  "users": "number[]"
}

PUT …/user-groups/{id}/ — update (same shape).
DELETE …/user-groups/{id}/ — delete. Destructive — confirm with the user first.

POST …/core/rbac/teams/access/ — set team access:

{
  "platform_key": "string (required)",
  "usergroup_id": "number (required)",
  "groups": "[{group_id, role}]",
  "users": "[{user_id, role}]"
}

Alerts

…/core/watched-groups/

GET / POST …/watched-groups/ — list / create watched group.
GET / PATCH / DELETE …/watched-groups/{id}/ — watched group detail / update / delete. DELETE is destructive — confirm with the user first.
GET / POST …/watched-groups/{watchedGroupPk}/watched-users/ — list / add watched users.
DELETE …/watched-users/{id}/ — remove watched user. Destructive — confirm with the user first.
GET / POST …/watched-groups/{watchedGroupPk}/watchers/ — list / add watchers.
PATCH / DELETE …/watchers/{id}/ — update / remove watcher (notification-event flags in body). DELETE is destructive — confirm with the user first.

Example

List the first page of organization users with their policies:

curl -s \
  "https://api.iblai.app/dm/api/core/platform/users/?platform_key=$IBLAI_ORG&platform_org=$IBLAI_ORG&page=1&page_size=10&return_policies=true" \
  -H "Authorization: Api-Token $IBLAI_API_KEY"

Notes

Most endpoints require platform_key={org} as a query param even on POST/PUT bodies that also carry it — send both.
The edX user-roles calls (list, promote/demote, bulk sync) are the only ones on the edX LMS/CMS host and take no platform_key; every other endpoint here is on the DM host under /api/core/…. Prefer the CMS host (studio.learn.iblai.app) for edX roles - it accepts every role key, including course-creator, which the LMS host rejects.
edX roles (this section) and DM rbac/roles (the Roles subsection below) are two unrelated systems that happen to share the word "role" - an edX role key like org-instructor is not a DM RBAC role id, and vice versa.
Policies bind a role (RBAC role id) to resources, users, and groups — create the Role first, then reference its id when creating the Policy.
DELETE on any sub-section is destructive — confirm with the user before removing groups, roles, policies, teams, watched groups/users, or watchers.

Reference material

references/edx-roles-reference.md - full edX role catalog (every global/course/org role key and what it grants), the list/assign/bulk-sync endpoint bodies and responses, and gotchas (inactive-user grant skipping, idempotency, course-creator's CMS-only restriction, Open edX release gates on course-limited-staff).