Request User Email Change

Request a verified email-address change for a user by ID.

The endpoint sends a confirmation link to the new address. The user's current email remains active until the confirmation flow succeeds.

Authentication

This endpoint requires a bearer access token for the System API with the system_api scope.

Endpoint

POST /api/v1/users/{userId}/email
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token for a System API client
Content-Type	Yes	Must be application/json

Path Parameters

Parameter	Type	Required	Description
userId	integer	Yes	User identifier

Query Parameters

This endpoint does not accept query parameters.

Request Body

{
  "newEmail": "[email protected]"
}

Request Fields

Field	Type	Required	Description
newEmail	string	Yes	New email address to verify. Maximum length: 254 characters.

Validation Rules

• newEmail is required and must not be blank
• newEmail must be a valid email address with a maximum length of 254 characters
• The portion before @ must not exceed 64 characters
• newEmail must differ from the user's current email address
• newEmail must not already belong to another user

Response

204 No Content

The request was accepted and Guardhouse submitted a confirmation email to the new address.

This endpoint does not return a response body on success. A 204 response means the verification flow started; it does not mean the user's email has already changed.

Errors

Status	When it happens
400 Bad Request	The request violates the email contract, matches the current address, or the confirmation request cannot be started
401 Unauthorized	The bearer token is missing, invalid, or expired
403 Forbidden	The token is valid but does not have access to this endpoint
404 Not Found	No user exists with the provided userId
409 Conflict	The new email address already belongs to another user

Error messages can be localized or revised. Branch on the HTTP status and operation context rather than comparing message text.

Behavior

• Guardhouse trims and lowercases newEmail before processing it.
• Guardhouse sends a confirmation link to the new address. The link is valid for 10 minutes.
• The current email remains unchanged until the user follows the confirmation link.
• After successful confirmation, Guardhouse updates the user's email and username, invalidates existing access, and sends a notification to the previous email address.
• Successful confirmation removes linked external sign-in connections; the user must link them again if they are still needed.
• Successful confirmation triggers the User Updated webhook flow.

Example

cURL

curl -X POST "https://your-tenant.guardhouse.cloud/api/v1/users/101/email" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "newEmail": "[email protected]"
  }'

.NET SDK

using Guardhouse.SDK.Models.Users;
using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapPost("/example/users/{userId:int}/email", async (
    int userId,
    IGuardhouseUsersClient usersClient) =>
{
    var requested = await usersClient.RequestEmailChangeAsync(
        userId,
        new RequestEmailChangeRequest
        {
            NewEmail = "[email protected]"
        });

    return requested ? Results.NoContent() : Results.NotFound();
});

Python (raw HTTP)

# The Python beta does not expose typed System API helpers.
# Use an authenticated HTTP client:
#
# response = requests.post(
#     "https://your-tenant.guardhouse.cloud/api/v1/users/101/email",
#     headers={
#         "Authorization": "Bearer YOUR_ACCESS_TOKEN",
#         "Content-Type": "application/json",
#     },
#     json={"newEmail": "[email protected]"},
# )

Notes

• Use this endpoint when the user must prove control of the new email address.
• Use Update User By ID for a direct trusted-administrator profile update when email verification is not required.
• Use Get User By ID after confirmation if you need the latest stored user record.
• See Webhook Events for the user-updated event contract.