AuthServer API Reference

var result = await authService.LoginWithPasswordAsync(
    new SqlOSPasswordLoginRequest(
        Email: request.Email,
        Password: request.Password,
        ClientId: "my-app",
        OrganizationId: null),
    httpContext);
 
if (result.RequiresOrganizationSelection)
    return Results.Ok(new
    {
        requiresOrgSelection = true,
        pendingAuthToken = result.PendingAuthToken,
        organizations = result.Organizations
    });
 
return Results.Ok(result.Tokens);

var result = await authService.SignUpAsync(
    new SqlOSSignupRequest(
        DisplayName: "Jane Doe",
        Email: "jane@example.com",
        Password: "s3cureP@ss",
        OrganizationName: "Acme Corp",
        ClientId: "my-app",
        OrganizationId: null),
    httpContext);
 
return Results.Ok(result.Tokens);

var tokens = await authService.SelectOrganizationAsync(
    new SqlOSSelectOrganizationRequest(
        PendingAuthToken: result.PendingAuthToken!,
        OrganizationId: selectedOrgId),
    httpContext);
 
return Results.Ok(tokens);

var tokens = await authService.RefreshAsync(
    new SqlOSRefreshRequest(
        RefreshToken: request.RefreshToken,
        OrganizationId: null));
 
return Results.Ok(tokens);

await authService.LogoutAsync(
    refreshToken: request.RefreshToken,
    sessionId: null);
 
return Results.Ok();

await authService.LogoutAllAsync(userId);

var validated = await authService.ValidateAccessTokenAsync(rawToken);
if (validated is null)
    return Results.Unauthorized();
 
var userId = validated.UserId;
var orgId = validated.OrganizationId;

var tokens = await authService.ExchangeCodeAsync(
    new SqlOSExchangeCodeRequest(
        Code: code,
        ClientId: "my-app"),
    httpContext);

var token = await authService.CreatePasswordResetTokenAsync(
    new SqlOSForgotPasswordRequest(Email: request.Email));
 
// Send token via email (you provide the email transport)
await emailService.SendResetEmail(request.Email, token);

await authService.ResetPasswordAsync(
    new SqlOSResetPasswordRequest(
        Token: request.Token,
        NewPassword: request.NewPassword));

var token = await authService.CreateEmailVerificationTokenAsync(
    new SqlOSCreateVerificationTokenRequest(Email: request.Email));

await authService.VerifyEmailAsync(
    new SqlOSVerifyEmailRequest(Token: request.Token));

var tokens = await authService.CreateSessionTokensForUserAsync(
    user, client, organizationId: org.Id,
    authenticationMethod: "oidc",
    userAgent: httpContext.Request.Headers.UserAgent,
    ipAddress: httpContext.Connection.RemoteIpAddress?.ToString());

var org = await adminService.CreateOrganizationAsync(
    new SqlOSCreateOrganizationRequest(
        Name: "Acme Corp",
        Slug: "acme",
        PrimaryDomain: "acme.com"));

var user = await adminService.CreateUserAsync(
    new SqlOSCreateUserRequest(
        DisplayName: "Jane Doe",
        Email: "jane@acme.com",
        Password: "s3cureP@ss"));

var membership = await adminService.CreateMembershipAsync(
    organizationId: org.Id,
    new SqlOSCreateMembershipRequest(
        UserId: user.Id,
        Role: "admin"));

var client = await adminService.CreateClientAsync(
    new SqlOSCreateClientRequest(
        ClientId: "my-app",
        Name: "My Application",
        Audience: "https://api.example.com",
        RedirectUris: ["https://example.com/callback"]));

var draft = await adminService.CreateSsoConnectionDraftAsync(
    new SqlOSCreateSsoConnectionDraftRequest(
        OrganizationId: org.Id,
        DisplayName: "Acme Okta SSO",
        PrimaryDomain: "acme.com",
        AutoProvisionUsers: true,
        AutoLinkByEmail: true));
 
// Now import the metadata:
await adminService.ImportSsoMetadataAsync(
    draft.Id,
    new SqlOSImportSsoMetadataRequest(MetadataXml: xml));

await adminService.ImportSsoMetadataAsync(
    connectionId,
    new SqlOSImportSsoMetadataRequest(MetadataXml: metadataXml));

var conn = await adminService.CreateOidcConnectionAsync(
    new SqlOSCreateOidcConnectionRequest(
        ProviderType: SqlOSOidcProviderType.Google,
        DisplayName: "Sign in with Google",
        ClientId: "google-client-id",
        ClientSecret: "google-client-secret",
        AllowedCallbackUris: ["https://example.com/callback"],
        UseDiscovery: true,
        DiscoveryUrl: "https://accounts.google.com/.well-known/openid-configuration",
        // remaining fields null/default
        Issuer: null, AuthorizationEndpoint: null,
        TokenEndpoint: null, UserInfoEndpoint: null,
        JwksUri: null, MicrosoftTenant: null,
        Scopes: null, ClaimMapping: null,
        ClientAuthMethod: null, UseUserInfo: null));

var orgs = await adminService.GetUserOrganizationsAsync(userId);
// Returns: [{ Id, Slug, Name, Role }, ...]

var isMember = await adminService.UserHasMembershipAsync(userId, orgId);

var email = SqlOSAdminService.NormalizeEmail("  Jane@ACME.com ");
// "jane@acme.com"

var result = await hrdService.DiscoverAsync(
    new SqlOSHomeRealmDiscoveryRequest(Email: request.Email));
 
// result.Mode: "password" | "sso" | "oidc"
// result.ConnectionId: SSO/OIDC connection ID (if applicable)
// result.OrganizationId: matched org ID

var ssoResult = await ssoService.StartAuthorizationAsync(
    new SqlOSSsoAuthorizationStartRequest(
        Email: request.Email,
        ClientId: "my-app",
        RedirectUri: "https://example.com/callback",
        State: state,
        CodeChallenge: codeChallenge,
        CodeChallengeMethod: "S256"));
 
// Redirect the user:
return Results.Redirect(ssoResult.AuthorizationUrl);

var tokens = await ssoService.ExchangeCodeAsync(
    new SqlOSPkceExchangeRequest(
        Code: code,
        ClientId: "my-app",
        RedirectUri: "https://example.com/callback",
        CodeVerifier: codeVerifier),
    httpContext);

var providers = await oidcService.ListEnabledProvidersAsync();
// [{ ConnectionId, ProviderType, DisplayName, ... }]

var result = await oidcService.StartAuthorizationAsync(
    new SqlOSStartOidcAuthorizationRequest(
        ConnectionId: connectionId,
        Email: request.Email,
        ClientId: "my-app",
        CallbackUri: "https://example.com/oidc/callback",
        State: state,
        Nonce: nonce,
        CodeChallenge: codeChallenge,
        CodeChallengeMethod: "S256"),
    ipAddress: httpContext.Connection.RemoteIpAddress?.ToString());
 
return Results.Redirect(result.AuthorizationUrl);

var result = await oidcService.CompleteAuthorizationAsync(
    new SqlOSCompleteOidcAuthorizationRequest(
        ConnectionId: connectionId,
        ClientId: "my-app",
        CallbackUri: "https://example.com/oidc/callback",
        Code: code,
        CodeVerifier: codeVerifier,
        Nonce: nonce,
        UserPayloadJson: null),
    ipAddress: httpContext.Connection.RemoteIpAddress?.ToString());
 
// result.UserId, result.Email, result.OrganizationId
// Now create a session:
var tokens = await authService.CreateSessionTokensForUserAsync(
    user, client, result.OrganizationId,
    result.AuthenticationMethod, userAgent, ipAddress);

var settings = await settingsService.GetResolvedSecuritySettingsAsync();
// settings.RefreshTokenLifetime, settings.SessionIdleTimeout, etc.

await settingsService.UpdateSecuritySettingsAsync(
    new SqlOSUpdateSecuritySettingsRequest(
        RefreshTokenLifetimeMinutes: 1440,
        SessionIdleTimeoutMinutes: 60,
        SessionAbsoluteLifetimeMinutes: 10080));

public sealed record SqlOSTokenResponse(
    string AccessToken,
    string RefreshToken,
    string SessionId,
    string ClientId,
    string? OrganizationId,
    DateTime AccessTokenExpiresAt,
    DateTime RefreshTokenExpiresAt);

public sealed record SqlOSLoginResult(
    bool RequiresOrganizationSelection,
    string? PendingAuthToken,
    IReadOnlyList<SqlOSOrganizationOption> Organizations,
    SqlOSTokenResponse? Tokens);

public sealed record SqlOSValidatedToken(
    ClaimsPrincipal Principal,
    string SessionId,
    string? UserId,
    string? OrganizationId,
    string? ClientId);

public sealed record SqlOSOrganizationOption(
    string Id,
    string Slug,
    string Name,
    string Role);