Version v3.0.0
API Reference
ProAuth exposes two REST APIs for managing and configuring your identity infrastructure. Starting with ProAuth 3.x, both APIs are available in v1 (legacy) and v2 (current).
Deprecation Notice
API v1 is deprecated as of ProAuth 3.0 and will be removed in a future major release. All new integrations should use API v2. Existing integrations should migrate to v2 at the earliest opportunity.
Management API
The Management API is used to manage and configure ProAuth server — customers, subscriptions, tenants, identity providers, client applications, certificates, custom views, and more.
| Version | Base Path | Status |
|---|---|---|
| v2 | /api/management/v2/ | ✅ Current |
| v1 | /api/management/v1/ | ⚠️ Deprecated |
- Management API v2 Reference — Current version with CQRS-lite command pattern
- Typed Identifiers — Domain-specific ID types used by the v2 .NET clients
- Management API v1 Reference — Legacy, maintained for backward compatibility
- Optimistic Concurrency (ETag / If-Match) — RFC 9110 concurrency contract for v2 mutations
User Store API
The User Store API manages users, groups, group memberships, user profiles, and credentials within a specific user store instance. It is always executed in the context of a specific user store (identified by the instanceId path parameter).
| Version | Base Path | Status |
|---|---|---|
| v2 | /api/userstore/v2/{instanceId}/ | ✅ Current |
| v1 | /api/userstore/v1/{instanceId}/ | ⚠️ Deprecated |
- User Store API v2 Reference — Current version with CQRS-lite command pattern
- User Store API v1 Reference — Legacy, maintained for backward compatibility
SCIM API
The SCIM (System for Cross-domain Identity Management) API provides standardized user and group provisioning. The SCIM API is not versioned separately and continues to follow the SCIM 2.0 specification.
API Versioning
ProAuth uses URL-based API versioning. The version number is embedded in the URL path:
/api/management/v1/customer ← v1 (deprecated)
/api/management/v2/customer ← v2 (current)Both v1 and v2 endpoints are served simultaneously. v1 endpoints will continue to function for the lifetime of the ProAuth 3.x release series to give integrators time to migrate.
Key Differences Between v1 and v2
| Aspect | v1 | v2 |
|---|---|---|
| Pattern | Traditional CRUD REST | CQRS-lite with typed commands |
| Create payloads | DTOs with Dto suffix | Create{Entity}Command |
| Update payloads | DTOs with Dto suffix | Update{Entity}Command |
| Patch payloads | Not available | Patch{Entity}Command (type-safe) |
| Read responses | DTOs with Dto suffix | Clean entity names (e.g., ClientApp) |
| .NET identifier types | Guid | Typed IDs such as ClientAppId, SubscriptionId, and UserId |
| Relationship management | Inline collections or separate endpoints | Dedicated relationship endpoints |
| OpenAPI spec | Available at /openapi/v1.json | Available at /openapi/v2.json |
| Client libraries | ProAuth.Clients.Management (v1) | ProAuth.Clients.Management.V2 |
Client Libraries
Pre-generated .NET client packages are available for both API versions:
Management API:
ProAuth.Clients.Management— v1 client (deprecated)ProAuth.Clients.Management.V2— v2 client (recommended)
User Store API:
ProAuth.Clients.UserStore— v1 client (deprecated)ProAuth.Clients.UserStore.V2— v2 client (recommended)
Install from the ProAuth NuGet feed:
bash
dotnet add package ProAuth.Clients.Management.V2 --source "https://pkgs.dev.azure.com/4tecture/_packaging/Products/nuget/v3/index.json"The v2 .NET clients expose resource identifiers as typed values from ProAuth.TypedIds, for example ClientAppId, SubscriptionId, IdpInstanceId, UserId, and GroupId. These values serialize as normal UUID strings. Direct HTTP integrations and custom OpenAPI clients can continue to treat ID fields and path parameters as UUIDs unless they opt into the x-reafx-typed-id metadata.
OpenAPI / Swagger
Both API versions expose interactive OpenAPI documentation via Scalar:
- Management API v1:
https://{proauth-host}/scalar/v1 - Management API v2:
https://{proauth-host}/scalar/v2
The raw OpenAPI specification documents are available at:
- Management API v1:
https://{proauth-host}/openapi/v1.json - Management API v2:
https://{proauth-host}/openapi/v2.json
TIP
Use the Scalar UI for interactive API exploration and testing. Export the OpenAPI JSON to generate client code in any language using tools like NSwag, AutoRest, or openapi-generator.