Getting Started Guide

This guide will help you get up and running with the SaaS Auth API quickly.

Prerequisites

Before you begin, ensure you have the following installed:

Go 1.24.1 or later
Docker and Docker Compose
Git
An IDE or text editor (VSCode recommended with Go extension)

Quick Start

Follow these steps to start using the SaaS Auth API:

1. Clone the Repository

git clone https://github.com/yersonargotev/saas-auth-api.git
cd saas-auth-api

2. Start the Development Environment

The easiest way to get started is using Docker Compose:

docker-compose -f docker-compose.dev.yml up

This will:

Start PostgreSQL and Redis containers
Run database migrations automatically
Start the API with hot reloading
Expose the API on http://localhost:3000

3. Test the API

Make a request to the health check endpoint to verify everything is working:

curl http://localhost:3000/health

You should receive a JSON response similar to:

{
  "status": "ok",
  "version": "0.1.0",
  "database": "ok",
  "redis": "ok",
  "timestamp": "2023-06-01T12:34:56Z"
}

4. Create an Admin User

Create your first admin user:

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123",
    "first_name": "Admin",
    "last_name": "User"
  }'

In a real production environment, the API would send a verification email. For development, you can check the logs to find the verification token:

docker-compose -f docker-compose.dev.yml logs api | grep "Email verification token"

You’ll see a log entry like:

Email verification token generated [email protected] user_id=... token=123e4567-e89b-12d3-a456-426614174000

Use this token to verify the email:

curl -X POST http://localhost:3000/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "123e4567-e89b-12d3-a456-426614174000"
  }'

Now you can login:

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'

The response will contain your access and refresh tokens:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

6. Using the API

You can now use the API with your access token:

curl -X GET http://localhost:3000/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Project Configuration

The default configuration is in config/config.yaml. For development, you can modify this file directly.

Key configuration options:

app:
  port: 3000            # API port

database:
  host: localhost       # PostgreSQL host
  port: 5432            # PostgreSQL port
  user: postgres        # PostgreSQL user
  password: postgres    # PostgreSQL password
  name: saas_auth       # PostgreSQL database name

redis:
  host: localhost       # Redis host
  port: 6379            # Redis port
  password: ""          # Redis password

jwt:
  secret: supersecretkey-change-in-production  # JWT secret
  access_ttl: 15m       # Access token lifetime
  refresh_ttl: 24h      # Refresh token lifetime

auth:
  password_salt: change-this-in-production     # Password salt
  rate_limit:
    enabled: true       # Enable rate limiting
    requests: 100       # Requests per duration
    duration: 1m        # Duration for rate limit

Development Workflow

Directory Structure

The project follows a clean architecture approach:

cmd/api/main.go: Application entry point
internal/: Core application code
- auth/: Authentication domain
- user/: User domain
- role/: Role domain
- apiKey/: API key domain
pkg/: Shared code
migrations/: Database migrations
tests/: Test suite

Making Changes

Modify Domain Models: If you need to add or change a business entity, start with the domain models in the respective domain directory.
Update Repositories: If your changes affect data storage, update the repository implementations.
Modify Services: Update the service layer to implement new business logic.
Update HTTP Handlers: Finally, add or modify HTTP handlers to expose new functionality via the API.

Running Tests

To run tests:

# Unit tests
go test ./tests/unit/...

# Integration tests
go test ./tests/integration/...

# End-to-end tests
go test ./tests/e2e/...

# All tests
go test ./...

Database Migrations

Migrations are automatically applied when the application starts. If you need to create a new migration:

Create a new migration file in the migrations directory following the naming convention:
```
000002_migration_name.up.sql
000002_migration_name.down.sql
```
Write your migration SQL in the .up.sql file and the rollback SQL in the .down.sql file.

Common Use Cases

Creating a New User

curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123",
    "first_name": "John",
    "last_name": "Doe"
  }'

Creating an API Key

curl -X POST http://localhost:3000/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key"
  }'

Note: Save the key field from the response, as it won’t be shown again.

Creating a Role

curl -X POST http://localhost:3000/api/v1/roles \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "description": "Can edit content"
  }'

Assigning a Role to a User

curl -X POST http://localhost:3000/api/v1/users/USER_ID/roles \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "ROLE_ID"
  }'

Troubleshooting

Common Issues

Connection to PostgreSQL or Redis fails
- Check that the PostgreSQL and Redis containers are running
- Verify the connection settings in config/config.yaml
JWT token invalid
- Ensure you’re using the correct token
- Check if the token has expired
- Verify the JWT secret in the configuration
Permission denied
- Check if the user has the required role
- Verify that the role has the necessary permissions
Rate limiting issues
- Check your rate limit configuration
- Use a different IP or user account if you’ve exceeded limits

Getting Help

If you encounter any issues not covered here:

Check the logs with docker-compose -f docker-compose.dev.yml logs api
Look for error messages in the API response
Review the relevant documentation for the feature you’re using
Open an issue on the project’s GitHub repository

Next Steps

Explore the API documentation in docs/swagger.yaml
Learn about the architecture in the Architecture Overview document
Review the API Usage Examples for common patterns
Check the Production Deployment Guide when you’re ready to deploy