When making a custom request to an Okta API endpoint that does not have a dedicated method in the Okta .NET SDK, the following error may be returned:

Error 400: The request body was not well-formed

This issue occurs when using generic methods like GetAsync, PostAsync, PutAsync, or DeleteAsync to interact with the API.

• Okta .NET Authentication SDK

The error can occur by manually serializing the body of the request (that is, payload) into JSON before passing it to the Okta .NET SDK client (IOktaClient or AuthenticationClient). The SDK is designed to automatically handle the serialization of C# objects into a JSON payload.

When a pre-serialized JSON string is provided as the payload, the SDK attempts to serialize it again. This double serialization corrupts the JSON structure (for example, by adding escape characters), leading to a malformed request body that the Okta API cannot parse, resulting in the 400 error.

To resolve this issue, do not manually serialize the request object. Instead, pass the C# object directly to the Payload property of the HttpRequest object. The SDK will correctly serialize the object and set the appropriate Content-Type: application/json header.

Correct Implementation Example:

The following example demonstrates the correct way to build and send a request for a password recovery using the authnClient.

1. Create an instance of the options object for the desired endpoint (for example, ForgotPasswordOptions).
2. Populate the properties of the options object.
3. Create a new HttpRequest object.
4. Assign the API endpoint URI to the Uri property.
5. Crucially, assign the C# object representing the body directly to the Payload property.
6. (Optional) Add any custom headers.
7. Await the call to the generic PostAsync method, passing the prepared HttpRequest.

// 1. & 2. Create and populate the C# payload object (request body).
var forgotPasswordOptions = new ForgotPasswordOptions()
{
    FactorType = FactorType.Email,
    RelayState = "/myapp/some/deep/link/i/want/to/return/to",
    UserName = "bob-user@test.com",
};

// 3. Create a new HttpRequest object.
var request = new HttpRequest()
{
    // 4. Set the endpoint URI.
    Uri = "/api/v1/authn/recovery/password",

    // 5. Assign the C# object directly to the Payload. Do NOT serialize it first.
    Payload = forgotPasswordOptions,
};

// 6. (Optional) Add a custom header.
request.Headers["User-Agent"] = "MyUserAgentInfo";

// 7. Await the PostAsync call. The SDK will handle serialization.
var authResponse = await authnClient.PostAsync<AuthenticationResponse>(request);

By following this flow, the SDK will generate a well-formed request body, and the API call will succeed.

The key takeaway is step 1. When creating an object, it is possible to assign it straight to the payload so that the user can provide it as the request body (step 5). No transformation is necessary; the Okta SDK will do it internally.

Related References

• Okta Auth .NET SDK - Call Other API Endpoints