This page documents the data model architecture and JSON serialization mechanisms used throughout the Auth0.NET SDK. It covers model organization patterns, custom JSON converters, and serialization configuration that enables communication with Auth0's APIs.
The SDK organizes data models into primary categories distributed across package boundaries. The Auth0.Core package provides foundational error and rate-limiting models used by both the Authentication and Management APIs.
Sources:
Request and response models are distinct types even when representing the same entity. Models utilize JsonProperty attributes (Newtonsoft) or JsonPropertyName (System.Text.Json) to map PascalCase C# properties to the specific JSON fields (often snake_case) required by the API.
| Entity | Request Model | Response Model | Purpose |
|---|---|---|---|
| User Info | N/A (GET) | UserInfo | Standard OIDC claims mapping src/Auth0.AuthenticationApi/Models/UserInfo.cs17-18 |
| API Error | N/A | ApiError | Capture error info from failed requests src/Auth0.Core/Exceptions/ApiError.cs13-14 |
Sources:
The SDK uses different serialization engines depending on the package and generation method:
Auth0.Core and Auth0.AuthenticationApi. It relies on [JsonProperty] and [JsonConverter] attributes to control transformations src/Auth0.Core/Exceptions/ApiError.cs2-12 The dependency is defined in the core project src/Auth0.Core/Auth0.Core.csproj18ManagementApi v8 models to align with modern .NET standards. This dependency is explicitly managed for older frameworks src/Auth0.ManagementApi/Auth0.ManagementApi.csproj42-45The modern Management API code introduces specific types to handle API nuances:
The SDK implements specialized JsonConverter classes to handle non-standard Auth0 API response patterns or polymorphic fields.
The ApiErrorConverter normalizes various error formats returned by different Auth0 services into a consistent ApiError object. It maps different JSON keys to standard C# properties src/Auth0.Core/Serialization/ApiErrorConverter.cs12-18
| JSON Key | C# Property |
|---|---|
code | ErrorCode |
name | Error |
description | Message |
error_description | Message |
Unmapped properties are automatically captured in an ExtraData dictionary src/Auth0.Core/Serialization/ApiErrorConverter.cs49-54
Sources:
| Converter | Purpose | Usage Example |
|---|---|---|
StringOrObjectAsStringConverter | Handles fields that might be a string or a complex object, ensuring they are always treated as a string in .NET. | UserInfo.Locale src/Auth0.AuthenticationApi/Models/UserInfo.cs164-165 |
StringOrStringArrayJsonConverter | Handles fields that can be a single string or an array of strings (like OAuth2 scopes). | ReadJson logic src/Auth0.Core/Serialization/StringOrStringArrayJsonConverter.cs16-33 |
FlexibleDateTimeConverter | Handles various date formats returned by the Authentication API. | Used in Auth0.AuthenticationApi |
Sources:
When an API call fails, the ApiException.CreateSpecificExceptionAsync method determines the correct exception type based on the HTTP status code src/Auth0.Core/Exceptions/ApiException.cs54-63
RateLimitApiException.CreateAsync, which parses both the RateLimit headers and the ApiError body src/Auth0.Core/Exceptions/RateLimitApiException.cs63-66ErrorApiException.CreateAsync src/Auth0.Core/Exceptions/ErrorApiException.cs72-75If the error body is not valid JSON, the ApiError.Parse method captures the raw string content into both the Error and Message properties to ensure the diagnostic information is preserved src/Auth0.Core/Exceptions/ApiError.cs66-73
Sources:
Rate limit information is primarily delivered via HTTP headers. The SDK includes logic to parse these headers into structured objects. This includes standard rate limits and specific quota limits for clients and organizations.
Sources:
Refresh this wiki