Role Resolution Service - API Contract

GET /api/v1/user-roles/api/v1/user-roles

List all resolved role assignments

Public

Response Example

{
  "data": [
    {
      "user_id": "usr_8f3a1b2c",
      "primary_role": "coordinator",
      "all_roles": [
        "coordinator",
        "mentor"
      ],
      "is_global_admin": false,
      "resolved_at": "2026-03-26T10:14:00Z"
    },
    {
      "user_id": "usr_9d4e2c3f",
      "primary_role": "admin",
      "all_roles": [
        "admin"
      ],
      "is_global_admin": true,
      "resolved_at": "2026-03-26T09:55:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 84
  }
}

GET /api/v1/user-roles/api/v1/user-roles/:userId

Resolve all roles for a specific user

Public

Response Example

{
  "user_id": "usr_8f3a1b2c",
  "primary_role": "coordinator",
  "all_roles": [
    "coordinator",
    "mentor"
  ],
  "is_global_admin": false,
  "resolved_at": "2026-03-26T10:14:00Z"
}

POST /api/v1/user-roles/api/v1/user-roles

Assign a role to a user

Public

Request Example

{
  "user_id": "usr_8f3a1b2c",
  "role": "coordinator",
  "is_primary": true
}

Response Example

{
  "user_id": "usr_8f3a1b2c",
  "primary_role": "coordinator",
  "all_roles": [
    "coordinator"
  ],
  "is_global_admin": false,
  "resolved_at": "2026-03-26T10:20:00Z"
}

PUT /api/v1/user-roles/api/v1/user-roles/:userId

Update role assignment for a user

Public

Request Example

{
  "primary_role": "admin",
  "all_roles": [
    "admin",
    "coordinator"
  ],
  "is_global_admin": false
}

Response Example

{
  "user_id": "usr_8f3a1b2c",
  "primary_role": "admin",
  "all_roles": [
    "admin",
    "coordinator"
  ],
  "is_global_admin": false,
  "resolved_at": "2026-03-26T10:25:00Z"
}

DELETE /api/v1/user-roles/api/v1/user-roles/:userId

Remove all role assignments for a user

Public

Response Example

{
  "deleted": true,
  "user_id": "usr_8f3a1b2c"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}