POST /api/v1/role-assignments
Assign a responsibility to an eligible school member.
Send x-api-key. The school and actor come from the verified key; body identities cannot override them. School OWNER or organization program_director. Organization ADMIN alone is read-only; a MEMBER needs the program_director responsibility.
Idempotency-Key is required. Reuse it only for the identical target and payload. X-Correlation-Id is optional.
Request body
subjectUserId (UUID) and role are required. Roles: program_director, coach, reviewer, head_of_sales, setter, closer. head_of_sales is assigned and removed by the school OWNER only (a program_director is refused with 403). scopeType defaults to organization; scopeId is null for organization and a UUID for program/enrollment. Only coach accepts enrollment scope; coach and reviewer accept program scope. Optional effectiveAt is an ISO date-time no later than the current day; reason is at most 500 characters.
curl -X POST "https://www.cohorte.io/api/v1/role-assignments" \
-H "x-api-key: $COHORTE_API_KEY" \
-H "Idempotency-Key: pedagogy-example-001" \
-H "Content-Type: application/json" \
-d '{"subjectUserId": "11111111-1111-4111-8111-111111111111", "role": "coach", "scopeType": "organization"}'
200 returns the result; a newly assigned responsibility returns 201. 400: invalid input or forbidden state transition. 401: invalid key. 403: insufficient current permission. 409: idempotency key conflicts with another or unverifiable intention.
replayed is a top-level boolean beside data and correlationId, not nested inside the resource.
A responsibility object; replayed indicates an identical retry. Dates are ISO date-time strings or null.
{
"success": true,
"replayed": false,
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"subjectUserId": "11111111-1111-4111-8111-111111111111",
"role": "coach",
"scopeType": "organization",
"scopeId": null,
"createdAt": "2026-10-16T08:00:00.000Z",
"updatedAt": "2026-10-16T08:00:00.000Z"
},
"correlationId": "22222222-2222-4222-8222-222222222222"
}
For enrollment-scoped coaching, first grant the organization coach responsibility, then assign the eligible coach to the enrollment. Scope restrictions remain enforced on retries.
