.NET SDK Reference

app.MapPost(
    "/api/session",
    async (
        LoginBody body,
        HttpContext http,
        SqlOSAuthService auth,
        CancellationToken ct) =>
    {
        var result = await auth.LoginWithPasswordAsync(
            new SqlOSPasswordLoginRequest(
                Email: body.Email,
                Password: body.Password,
                ClientId: "acme-web",
                OrganizationId: null),
            http,
            ct);
 
        return Results.Ok(result);
    });

var login = await authService.LoginWithPasswordAsync(
    new SqlOSPasswordLoginRequest(
        Email: email,
        Password: password,
        ClientId: clientId,
        OrganizationId: organizationId),
    httpContext,
    ct);

static IResult LoginOutcome(SqlOSLoginResult result)
{
    if (result.RequiresOrganizationSelection)
    {
        return Results.Ok(new
        {
            next = "select_organization",
            pendingAuthToken = result.PendingAuthToken,
            organizations = result.Organizations
        });
    }
 
    if (result.RequiresMfa)
    {
        return Results.Ok(new
        {
            next = result.RequiresMfaEnrollment ? "enroll_totp" : "verify_mfa",
            mfaToken = result.MfaToken,
            methods = result.MfaMethods
        });
    }
 
    return result.Tokens is { } tokens
        ? Results.Ok(new { next = "complete", tokens })
        : Results.Problem("SqlOS returned no next authentication state.");
}

var selected = await authService.SelectOrganizationForLoginAsync(
    new SqlOSSelectOrganizationRequest(
        PendingAuthToken: pendingAuthToken,
        OrganizationId: organizationId),
    httpContext,
    ct);
 
return LoginOutcome(selected);

var signup = await authService.SignUpAsync(
    new SqlOSSignupRequest(
        DisplayName: displayName,
        Email: email,
        Password: password,
        OrganizationName: organizationName,
        ClientId: clientId,
        OrganizationId: null),
    httpContext,
    ct);

var start = await authService.RequestEmailOtpAsync(
    new SqlOSEmailOtpStartRequest(
        Email: email,
        ClientId: clientId,
        OrganizationId: organizationId),
    httpContext,
    ct);
 
var login = await authService.VerifyEmailOtpAsync(
    new SqlOSEmailOtpVerifyRequest(
        ChallengeToken: start.ChallengeToken,
        Code: code),
    httpContext,
    ct);

options.AuthServer.ConfigurePhoneOtp(phone =>
{
    phone.Enabled = true;
    phone.TwilioAccountSid = builder.Configuration["SqlOS:PhoneOtp:TwilioAccountSid"];
    phone.TwilioAuthToken = builder.Configuration["SqlOS:PhoneOtp:TwilioAuthToken"];
    phone.TwilioVerifyServiceSid = builder.Configuration["SqlOS:PhoneOtp:TwilioVerifyServiceSid"];
    phone.DefaultRegion = "US";
});

var start = await authService.RequestPhoneOtpAsync(
    new SqlOSPhoneOtpStartRequest(
        PhoneNumber: phoneNumber,
        ClientId: clientId,
        OrganizationId: organizationId),
    httpContext,
    ct);
 
var login = await authService.VerifyPhoneOtpAsync(
    new SqlOSPhoneOtpVerifyRequest(
        ChallengeToken: start.ChallengeToken,
        Code: code),
    httpContext,
    ct);

var invitation = await authService.CreateEmailInvitationAsync(
    new SqlOSCreateEmailInvitationRequest(
        OrganizationId: organizationId,
        Email: "teammate@example.com",
        Role: "member",
        ClientId: clientId,
        RedirectUri: redirectUri),
    httpContext,
    ct);

var result = await authorizationServer.ExchangeAuthorizationCodeAsync(
    new SqlOSTokenRequest(
        GrantType: "authorization_code",
        Code: code,
        RedirectUri: redirectUri,
        ClientId: clientId,
        CodeVerifier: codeVerifier,
        RefreshToken: null,
        Resource: null),
    httpContext,
    ct);
 
var tokens = result.Tokens;

var validated = await authService.ValidateAccessTokenAsync(
    rawToken,
    expectedAudience: "https://api.example.com",
    ct);

var reset = await authService.RequestPasswordResetEmailAsync(
    new SqlOSForgotPasswordRequest(
        Email: email,
        ClientId: clientId),
    httpContext,
    ct);

var verificationToken = await authService.CreateEmailVerificationTokenAsync(
    new SqlOSCreateVerificationTokenRequest(Email: email),
    ct);
 
// Deliver verificationToken to that address through a trusted email workflow.
// Consume it only when the user later follows the verification link.
await authService.VerifyEmailAsync(
    new SqlOSVerifyEmailRequest(Token: tokenFromVerificationLink),
    ct);

var organization = await adminService.CreateOrganizationAsync(
    new SqlOSCreateOrganizationRequest(
        Name: "Acme",
        Slug: "acme",
        PrimaryDomain: "acme.com"),
    ct);
 
var user = await adminService.CreateUserAsync(
    new SqlOSCreateUserRequest(
        DisplayName: "Jane Doe",
        Email: "jane@acme.com",
        Password: null),
    ct);
 
var membership = await adminService.CreateMembershipAsync(
    organization.Id,
    new SqlOSCreateMembershipRequest(
        UserId: user.Id,
        Role: "admin"),
    ct);
 
var client = await adminService.CreateClientAsync(
    new SqlOSCreateClientRequest(
        ClientId: "acme-web",
        Name: "Acme Web",
        Audience: "https://app.example.com/api",
        RedirectUris: ["https://app.example.com/auth/callback"]),
    ct);

var draft = await adminService.CreateSsoConnectionDraftAsync(
    new SqlOSCreateSsoConnectionDraftRequest(
        OrganizationId: organization.Id,
        DisplayName: "Acme SSO",
        PrimaryDomain: "acme.com",
        AutoProvisionUsers: false,
        AutoLinkByEmail: true),
    ct);
 
var connection = await adminService.ImportSsoMetadataAsync(
    draft.Id,
    new SqlOSImportSsoMetadataRequest(MetadataXml: metadataXml),
    ct);

using SqlOS.Extensions;
 
await db.ProvisionUserSubjectAsync(
    subjectId: authUser.Id,
    displayName: authUser.DisplayName,
    email: authUser.DefaultEmail,
    externalRef: authUser.Id,
    cancellationToken: ct);
 
await db.SaveChangesAsync(ct);

using SqlOS.AuthServer.Extensions;
 
var validated = httpContext.GetSqlOSValidatedToken();
if (validated?.UserId is not { } subjectId)
{
    return Results.Unauthorized();
}
 
var decision = await fga.CheckAccessAsync(
    subjectId,
    permissionKey: "WORKSPACE_VIEW",
    resourceId);
 
if (!decision.Allowed)
{
    return Results.Forbid();
}

var filter = await fga.GetAuthorizationFilterAsync<Workspace>(
    subjectId,
    permissionKey: "WORKSPACE_VIEW");
 
var visible = await db.Workspaces
    .Where(filter)
    .OrderBy(workspace => workspace.Name)
    .ToListAsync(ct);

var recorded = await auditLogs.RecordAsync(
    new SqlOSAuditLogRecordRequest(
        Action: "workspace.created",
        OrganizationId: organizationId,
        UserId: userId,
        ApplicationKey: "acme-web",
        Actor: new SqlOSAuditActor("user", userId),
        Targets: [new SqlOSAuditTarget("workspace", workspaceId)],
        Context: SqlOSAuditContext.FromHttpContext(httpContext)),
    ct);

Task<SqlOSRenderedEmailPreview> PreviewAsync(
    string templateKey,
    IReadOnlyDictionary<string, object?> variables,
    CancellationToken cancellationToken = default);
 
Task<SqlOSSendEmailResult> SendAsync(
    SqlOSSendEmailRequest request,
    CancellationToken cancellationToken = default);

using System.Text.Json.Nodes;
 
await emailAdmin.CreateTemplateAsync(
    new SqlOSCreateEmailTemplateRequest(
        Key: "app.receipt",
        DisplayName: "Purchase receipt",
        SubjectTemplate: "Receipt {orderNumber}",
        HtmlBodyTemplate: "<p>Order <strong>{orderNumber}</strong>: {total}</p>",
        TextBodyTemplate: "Order {orderNumber}: {total}",
        Variables: new JsonObject
        {
            ["orderNumber"] = new JsonObject { ["description"] = "Order number" },
            ["total"] = new JsonObject { ["description"] = "Formatted total" }
        },
        IsActive: true),
    ct);
 
var preview = await email.PreviewAsync(
    "app.receipt",
    new Dictionary<string, object?>
    {
        ["orderNumber"] = "A-1234",
        ["total"] = "$42.00"
    },
    ct);

var sent = await email.SendAsync(
    new SqlOSSendEmailRequest(
        TemplateKey: "app.receipt",
        To: "buyer@example.com",
        Variables: new Dictionary<string, object?>
        {
            ["orderNumber"] = "A-1234",
            ["total"] = "$42.00"
        },
        IdempotencyKey: "receipt:A-1234"),
    ct);

var connect = await calendars.StartConnectAsync(
    new SqlOSStartCalendarConnectRequest(
        OidcConnectionId: oidcConnectionId,
        Mode: SqlOSCalendarIntegrationMode.ConnectionOnly,
        ReturnUri: "https://app.example.com/settings/calendar/callback",
        UserId: userId,
        OrganizationId: null,
        DisplayName: "Work calendar"),
    httpContext,
    ct);
 
return Results.Redirect(connect.AuthorizationUrl);

var connection = await calendars.GetConnectionAsync(
    calendarConnectionId,
    forUserId: validated.UserId,
    forOrganizationId: null,
    cancellationToken: ct);

var providerCalendars = await calendars.ListProviderCalendarsAsync(
    calendarConnectionId,
    forUserId: validated.UserId,
    cancellationToken: ct);
 
var primary = providerCalendars.First(calendar => calendar.IsPrimary);
 
await calendars.EnableCalendarSyncAsync(
    calendarConnectionId,
    primary.ProviderCalendarId,
    displayName: primary.DisplayName,
    forUserId: validated.UserId,
    cancellationToken: ct);
 
// SyncConnectionAsync is a trusted worker/admin method with no owner parameter.
var sync = await calendarSync.SyncConnectionAsync(calendarConnectionId, ct);
 
var events = await calendars.ListEventsAsync(
    calendarConnectionId,
    fromUtc: DateTime.UtcNow,
    toUtc: DateTime.UtcNow.AddDays(30),
    forUserId: validated.UserId,
    cancellationToken: ct);

var created = await calendarSync.CreateEventAsync(
    calendarConnectionId,
    primary.ProviderCalendarId,
    new SqlOSCalendarEventDraft(
        Subject: "Project review",
        StartsAtUtc: startsAtUtc,
        EndsAtUtc: endsAtUtc),
    forUserId: validated.UserId,
    cancellationToken: ct);

await calendars.DisconnectAsync(
    calendarConnectionId,
    reason: "user_disconnected",
    forUserId: validated.UserId,
    cancellationToken: ct);