AuthStack.Client 1.3.0

AuthStack.Client

AuthStack SDK for .NET - OAuth authentication client with social login support.

Installation

dotnet add package AuthStack.Client

Quick Start

using AuthStack.Client;
using AuthStack.Client.Enums;

// Create the client
var client = new AuthStackClient(new AuthStackConfig
{
    BaseUrl = "https://api.authstack.voostack.com"
});

// Initialize (restores any stored session)
await client.InitializeAsync();

// Listen for status changes
client.StatusChanged += (sender, status) =>
{
    Console.WriteLine($"Auth status changed: {status}");
};

// Login with email/password
var result = await client.LoginAsync("user@example.com", "password123");

if (result.IsSuccess)
{
    Console.WriteLine($"Logged in as {result.User!.Email}");
    Console.WriteLine($"Access token: {result.Tokens!.AccessToken}");
}
else
{
    Console.WriteLine($"Login failed: {result.Error}");
}

Features

• Email/password authentication
• OAuth provider login (Google, GitHub, Microsoft, Apple, Discord)
• Provider credentials access (use GitHub/Google tokens in your app)
• Token refresh
• Secure token storage (customizable)
• Async/await support
• Event-based status updates
• JWKS support for token validation

OAuth Provider Login

// Using an ID token (e.g., from Google Sign-In)
var result = await client.LoginWithProviderTokenAsync(
    OAuthProvider.Google,
    googleIdToken
);

// Using an authorization code (redirect flow)
var result = await client.LoginWithProviderCodeAsync(
    OAuthProvider.GitHub,
    authorizationCode,
    "https://myapp.com/callback"
);

Recommended GitHub Scopes

When using GitHub OAuth, request these scopes for full functionality:

Example OAuth URL:

https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID&scope=repo,read:user,user:email&redirect_uri=YOUR_REDIRECT_URI

Centralized OAuth Flow

AuthStack handles OAuth app configuration centrally, so you don't need your own OAuth credentials. Use GetProviderAuthUrlAsync() to start an OAuth flow:

// Get the OAuth authorization URL for GitHub
var authUrl = await client.GetProviderAuthUrlAsync(
    OAuthProvider.GitHub,
    "https://yourapp.com/oauth/callback"
);

// Redirect user to authUrl.AuthorizationUrl
// After authorization, use the code to link the provider
var linked = await client.LinkProviderWithCodeAsync(
    OAuthProvider.GitHub,
    codeFromCallback,
    "https://yourapp.com/oauth/callback"
);

This works with all supported providers:

• GitHub
• Google
• Microsoft
• Apple
• Discord

Provider Credentials

After linking an OAuth provider, you can retrieve the provider's access token to make API calls on behalf of the user:

// Get GitHub credentials to interact with GitHub API
var credentials = await client.GetProviderCredentialsAsync(OAuthProvider.GitHub);

// Use with Octokit (GitHub .NET SDK)
var github = new GitHubClient(new ProductHeaderValue("MyApp"));
github.Credentials = new Credentials(credentials.AccessToken);
var repos = await github.Repository.GetAllForCurrent();

// Or with HttpClient
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", credentials.AccessToken);
var response = await httpClient.GetAsync("https://api.github.com/user/repos");

The ProviderCredentials object contains:

• AccessToken - OAuth access token for the provider
• RefreshToken - Refresh token (if available)
• ExpiresAt - Token expiration time (if known)
• Scopes - Granted OAuth scopes
• IsExpired - Whether the token has expired

Token Management

// Check authentication status
if (client.IsAuthenticated)
{
    // Get current user
    var user = client.CurrentUser;
    Console.WriteLine($"Hello, {user!.FullName}");

    // Get access token for API calls
    var accessToken = client.AccessToken;
}

// Refresh token
var success = await client.RefreshTokenAsync();

// Logout
await client.LogoutAsync();

Custom Token Storage

By default, tokens are stored in memory. For production, implement ITokenStorage:

public class SecureTokenStorage : ITokenStorage
{
    public Task SaveTokensAsync(AuthTokens tokens, CancellationToken ct = default)
    {
        // Save to secure storage
    }

    public Task<AuthTokens?> GetTokensAsync(CancellationToken ct = default)
    {
        // Retrieve from secure storage
    }

    public Task ClearTokensAsync(CancellationToken ct = default)
    {
        // Clear from secure storage
    }

    public Task<bool> HasTokensAsync(CancellationToken ct = default)
    {
        // Check if tokens exist
    }
}

// Use custom storage
var client = new AuthStackClient(new AuthStackConfig
{
    BaseUrl = "https://api.authstack.voostack.com",
    TokenStorage = new SecureTokenStorage()
});

JWKS Token Validation

AuthStack supports JWKS (JSON Web Key Set) for validating tokens without shared secrets. This is useful for backend services that need to verify AuthStack tokens.

.NET Backend Validation

services.AddAuthentication()
    .AddJwtBearer(options =>
    {
        options.Authority = "https://api.authstack.voostack.com";
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = "https://api.authstack.voostack.com",
            ValidateAudience = true,
            ValidAudience = "authstack"
        };
    });

Endpoints

API Reference

AuthStackClient

Events

License

MIT