Skip to main content

​
Assign Role to User

Assign a role to a specific user.

​
Endpoint

POST /api/Roles/assign

​
Authorization

Requires Administrator role.

​
Request Body

​
userId
string
required
ID of the user to assign the role to
​
roleName
string
required
Name of the role to assign (e.g., “Administrator”, “User”, “Manager”)

​
Response

​
status
integer
HTTP status code: 204 No Content on success

​
Example Request

curl -X POST https://api.sapfiai.com/api/Roles/assign \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "auth0|123456789",
    "roleName": "Manager"
  }'

​
Validation Rules

  • User must exist in the system
  • Role must exist in the system
  • User cannot have duplicate role assignments

​
Remove Role from User

Remove a role assignment from a user.

​
Endpoint

POST /api/Roles/remove

​
Authorization

Requires Administrator role.

​
Request Body

​
userId
string
required
ID of the user to remove the role from
​
roleName
string
required
Name of the role to remove

​
Response

​
status
integer
HTTP status code: 204 No Content on success

​
Example Request

curl -X POST https://api.sapfiai.com/api/Roles/remove \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "auth0|123456789",
    "roleName": "Manager"
  }'

​
Validation Rules

  • User must exist in the system
  • Role must exist in the system
  • User must currently have the role assigned

​
Get User Roles

Retrieve all roles assigned to a specific user.

​
Endpoint

GET /api/Roles/user/{userId}

​
Authorization

Requires Administrator role.

​
Path Parameters

​
userId
string
required
ID of the user to retrieve roles for

​
Response

​
roles
array
Array of role names assigned to the user

​
Example Request

curl -X GET https://api.sapfiai.com/api/Roles/user/auth0|123456789 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

[
  "User",
  "Manager"
]

​
Common Use Cases

​
Promote User to Administrator

// First, get current user roles
var currentRoles = await client.GetAsync(
    $"https://api.sapfiai.com/api/Roles/user/{userId}"
).Content.ReadFromJsonAsync<List<string>>();

// Assign Administrator role
var assignCommand = new
{
    UserId = userId,
    RoleName = "Administrator"
};

await client.PostAsync(
    "https://api.sapfiai.com/api/Roles/assign",
    new StringContent(
        JsonSerializer.Serialize(assignCommand),
        Encoding.UTF8,
        "application/json"
    )
);

​
Revoke Administrative Access

// Remove Administrator role
var removeCommand = new
{
    UserId = userId,
    RoleName = "Administrator"
};

await client.PostAsync(
    "https://api.sapfiai.com/api/Roles/remove",
    new StringContent(
        JsonSerializer.Serialize(removeCommand),
        Encoding.UTF8,
        "application/json"
    )
);

// Verify removal
var updatedRoles = await client.GetAsync(
    $"https://api.sapfiai.com/api/Roles/user/{userId}"
).Content.ReadFromJsonAsync<List<string>>();

​
Batch Role Assignment

var usersToPromote = new[] 
{ 
    "auth0|123456789", 
    "auth0|987654321" 
};

foreach (var userId in usersToPromote)
{
    var command = new
    {
        UserId = userId,
        RoleName = "Manager"
    };

    await client.PostAsync(
        "https://api.sapfiai.com/api/Roles/assign",
        new StringContent(
            JsonSerializer.Serialize(command),
            Encoding.UTF8,
            "application/json"
        )
    );
}

​
Error Responses

​
400
error
Bad Request - Invalid request parameters, user not found, or role not found
{
  "errors": {
    "UserId": ["User not found"],
    "RoleName": ["Role not found"]
  }
}
​
403
error
Forbidden - User does not have Administrator role
​
409
error
Conflict - Role already assigned (for assign) or role not assigned (for remove)

​
Best Practices

Always check if a user already has a role before assigning it to avoid unnecessary API calls and potential errors.
Log all role assignments and removals for security auditing purposes. Consider implementing a webhook or event system to track these changes.
Always check response status codes and handle errors appropriately. A 400 error may indicate the user or role doesn’t exist.
Role names are case-sensitive in the request but matched case-insensitively. Use the predefined role constants: “Administrator”, “User”, “Manager”.

Build docs developers (and LLMs) love

Get started for freeTalk to us