Skip to main content
This quickstart guide will help you get a SAPFIAI API instance up and running locally in just a few minutes.

​
Prerequisites Check

Before starting, verify you have the required tools:
1

Verify .NET 8.0 SDK

Open a terminal and check your .NET version:
dotnet --version
You should see version 8.0.x or higher. If not, download .NET 8.0 SDK.
2

Verify SQL Server

Check if SQL Server LocalDB is available:
sqllocaldb info
If you see MSSQLLocalDB in the list, you’re ready. Otherwise, install SQL Server Express or use SQLite instead.
If you prefer SQLite over SQL Server, update the connection string in src/Web/appsettings.json:
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=sapfiai.db"
  }
}
The application will automatically detect and use SQLite.

​
Quick Start Steps

1

Clone the Repository

Clone the SAPFIAI repository to your local machine:
git clone <repository-url>
cd SAPFIAI
Replace <repository-url> with your actual repository URL.
2

Restore Dependencies

Restore all NuGet packages:
dotnet restore
This will download all required dependencies for the solution.
3

Configure Database Connection (Optional)

The default configuration uses SQL Server LocalDB. If you want to customize:Open src/Web/appsettings.json and update the connection string:
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=SAPFIAIDb;Trusted_Connection=true;MultipleActiveResultSets=true"
  }
}

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=SAPFIAIDb;Trusted_Connection=true;MultipleActiveResultSets=true"
  }
}
4

Apply Database Migrations

Create and initialize the database:
dotnet ef database update --project src/Infrastructure --startup-project src/Web
This will:
  • Create the database if it doesn’t exist
  • Apply all pending migrations
  • Set up the schema with all required tables
If you encounter an error, make sure the EF Core tools are installed:
dotnet tool install --global dotnet-ef
5

Configure JWT Secret (Important)

The default JWT secret is insecure. Change it before running the application!
Update the JWT configuration in src/Web/appsettings.json:
{
  "Jwt": {
    "Key": "YOUR-SUPER-SECRET-KEY-AT-LEAST-32-CHARACTERS-LONG",
    "Issuer": "SAPFIAI",
    "Audience": "SAPFIAI-Users",
    "ExpireMinutes": "60"
  }
}
For production, use environment variables or user secrets instead of storing keys in appsettings.json.
6

Run the Application

Start the API server:
dotnet run --project src/Web
You should see output similar to:
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
7

Access the API

Open your browser and navigate to:

Swagger UI

Interactive API documentation

Health Check

Verify the API is running
You should see the Swagger UI with all available endpoints.

​
Testing the API

Let’s test the API by registering a new user and logging in.

​
1. Register a New User

Using the Swagger UI or cURL: 
curl -X POST https://localhost:5001/api/Authentication/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Test123!@#",
    "confirmPassword": "Test123!@#",
    "userName": "testuser"
  }'

{
  "success": true,
  "userId": "abc123-def456-ghi789",
  "message": "Usuario registrado exitosamente"
}

​
2. Login

Authenticate with the newly created user: 
curl -X POST https://localhost:5001/api/Authentication/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Test123!@#"
  }'

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "xW3k9pLmN7vQ2rT8yU4jK5sF1hG6dA0zC...",
  "refreshTokenExpiry": "2026-03-12T10:30:00Z",
  "user": {
    "id": "abc123-def456-ghi789",
    "userName": "testuser",
    "email": "[email protected]"
  },
  "requires2FA": false
}

​
3. Make an Authenticated Request

Use the token from the login response to make authenticated requests: 
curl -X GET https://localhost:5001/api/Permissions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Copy the token value from the login response and paste it into Swagger UI by clicking the Authorize button at the top right.

​
Exploring the Project Structure

Now that your API is running, let’s explore the project structure: 
SAPFIAI/
├── src/
│   ├── Domain/              # Core business logic and entities
│   │   ├── Entities/        # Domain entities (User, Permission, etc.)
│   │   ├── Enums/           # Domain enumerations
│   │   └── ValueObjects/    # Value objects
│   │
│   ├── Application/         # Use cases and business rules
│   │   ├── Users/           # User-related commands/queries
│   │   │   ├── Commands/    # Write operations (Login, Register)
│   │   │   └── Queries/     # Read operations (GetUser)
│   │   ├── Permissions/     # Permission management
│   │   ├── Roles/           # Role management
│   │   └── Security/        # Security operations
│   │
│   ├── Infrastructure/      # External concerns
│   │   ├── Data/            # EF Core DbContext and configurations
│   │   ├── Services/        # Service implementations
│   │   ├── Identity/        # ASP.NET Identity configuration
│   │   └── BackgroundJobs/  # Scheduled tasks
│   │
│   └── Web/                 # API presentation layer
│       ├── Endpoints/       # Minimal API endpoints
│       ├── Middleware/      # Custom middleware
│       └── Program.cs       # Application entry point
│
├── tests/                   # Test projects
│   ├── Application.UnitTests/
│   ├── Application.FunctionalTests/
│   ├── Domain.UnitTests/
│   └── Infrastructure.IntegrationTests/
│
└── docs/                    # Documentation

​
Next Steps

Congratulations! You now have a running SAPFIAI API instance. Here’s what to explore next:

Installation Guide

Detailed installation and configuration options

Authentication

Learn about all authentication endpoints

Architecture

Understand the Clean Architecture layers

Creating Use Cases

Learn how to add new features using CQRS

​
Common Issues

If ports 5000 or 5001 are already in use, you can change them in src/Web/Properties/launchSettings.json:
{
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7001;http://localhost:7000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}
If you can’t connect to the database:
  1. Verify SQL Server LocalDB is running: 
    sqllocaldb info
sqllocaldb start MSSQLLocalDB
  2. Try using SQLite instead by changing the connection string to: 
    "DefaultConnection": "Data Source=sapfiai.db"
If dotnet ef commands don’t work:
dotnet tool install --global dotnet-ef
dotnet tool update --global dotnet-ef
Then restart your terminal and try again.
If you see SSL certificate errors in your browser:
dotnet dev-certs https --trust
This will install and trust the development certificate.

​
Running Tests

To verify everything is working correctly, run the test suite: 
# Run all tests
dotnet test

# Run with code coverage
dotnet test /p:CollectCoverage=true /p:CoverageReportFormat=opencover
All tests should pass if the setup is correct.

​
Development Tips

Hot Reload: Use dotnet watch for automatic recompilation on file changes:
dotnet watch run --project src/Web
Swagger in Production: By default, Swagger is only enabled in Development. To enable it in other environments, modify the Swagger configuration in src/Web/DependencyInjection.cs.
Database Reset: To reset the database and start fresh:
dotnet ef database drop --project src/Infrastructure --startup-project src/Web
dotnet ef database update --project src/Infrastructure --startup-project src/Web

Build docs developers (and LLMs) love

Get started for freeTalk to us