Getting Started with the API

First-time local setup guide for AuthOS. Learn how to initialize your development environment, configure OAuth providers, and start the service.

Updated Dec 29, 2025 Edit this page

Getting Started with the API

This guide provides step-by-step instructions for setting up AuthOS for local development. Follow these steps to go from zero to a running instance with your first organization.

Prerequisites

Before you begin, ensure you have the following installed:

  • Docker (version 20.10 or later)
  • Docker Compose (version 2.0 or later)
  • OpenSSL (for generating cryptographic keys)

Verify installations:

docker --version
docker-compose --version
openssl version

Verification Flow

graph TD
    A[Install Prerequisites] --> B[Run Setup Script]
    B --> C{Configure Auth}
    C -->|Password| D[Set Owner Password]
    C -->|OAuth| E[Configure GitHub App]
    D --> F[Start Service]
    E --> F
    F --> G[Log in as Owner]
    G --> H[Create Organization]
    H --> I[Approve Organization]

Step 1: Initialize Environment

The platform requires several cryptographic secrets (RSA key pair, encryption key) to operate. An automated setup script generates these for you.

From the api/ directory, run:

./scripts/setup.sh

This script will:

  • Copy .env.example to .env
  • Generate an RSA key pair for JWT signing
  • Generate a 32-byte encryption key for storing OAuth credentials
  • Configure your .env file with all required secrets

If .env already exists, the script will prompt before overwriting and create a timestamped backup.

Step 2: Configure Platform Owner

The platform owner is the super administrator who can approve organizations and manage platform-level resources.

Edit .env and set your email address:

PLATFORM_OWNER_EMAIL=your-email@example.com

Password-Based Platform Owner Login (Optional)

For simplified initial setup without configuring OAuth providers, you can enable password-based authentication for the platform owner:

PLATFORM_OWNER_EMAIL=your-email@example.com
PLATFORM_OWNER_PASSWORD=your-secure-password

When both PLATFORM_OWNER_EMAIL and PLATFORM_OWNER_PASSWORD are set:

  • The platform owner account is created/updated on startup with the specified password
  • The email is automatically marked as verified
  • You can log in using POST /api/auth/login with email and password
  • You can change the password by updating the environment variable and restarting the service

This is particularly useful for:

  • Initial platform setup without OAuth configuration
  • Development and testing environments
  • Environments where OAuth providers are not available

Note: If you only set PLATFORM_OWNER_EMAIL (without password), you must log in via one of the configured OAuth providers.

Step 3: Configure Admin OAuth Provider (Optional with Password Auth)

Platform owners and organization administrators can authenticate via OAuth. Configure at least one OAuth provider to enable OAuth-based admin login.

Skip this step if: You’re using password-based authentication (PLATFORM_OWNER_PASSWORD is set) and don’t need OAuth login.

  1. Navigate to GitHub Developer Settings
  2. Click New OAuth App
  3. Fill in the application details:
    • Application name: AuthOS (Local)
    • Homepage URL: http://localhost:3000
    • Authorization callback URL: http://localhost:3000/auth/admin/github/callback
  4. Click Register application
  5. Copy the Client ID and generate a new Client Secret

Edit .env and add your GitHub credentials:

PLATFORM_GITHUB_CLIENT_ID=your_github_client_id
PLATFORM_GITHUB_CLIENT_SECRET=your_github_client_secret
PLATFORM_GITHUB_REDIRECT_URI=http://localhost:3000/auth/admin/github/callback

Note: You can also configure Google or Microsoft OAuth providers. The platform only requires one provider to be configured for admin login.

Step 4: Start the Service

Start AuthOS with Docker Compose using SQLite (default database):

docker-compose up --build sso-sqlite

The service will:

  • Build the Docker image
  • Run database migrations
  • Create the platform owner user (if it doesn’t exist)
  • Start listening on port 3000

You should see output indicating the server is running:

sso-sqlite-1  | Server running on 0.0.0.0:3000

Step 5: Your First Workflow

Now that the service is running, complete these steps to bootstrap your platform:

5.1. Log in as Platform Owner

Choose one of the following methods to obtain your platform owner access token:

Option A: Password-Based Login

If you configured PLATFORM_OWNER_PASSWORD, use the login API:

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-secure-password"
  }'

Response:

{
  "access_token": "eyJhbGc...",
  "refresh_token": "...",
  "expires_in": 900
}

Save the access_token for use in subsequent requests.

Option B: OAuth-Based Login

Navigate to the admin login endpoint in your browser:

http://localhost:3000/auth/admin/github

Authorize the application with your GitHub account. Ensure the email associated with your GitHub account matches PLATFORM_OWNER_EMAIL.

After successful authentication, you’ll be redirected with an access token.

5.2. Create Your First Organization

Organizations are multi-tenant containers for users, services, and OAuth configurations.

Using the access token from step 5.1, create an organization:

curl -X POST http://localhost:3000/api/organizations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme",
    "name": "Acme Corporation",
    "tier_id": 1
  }'

Response:

{
  "id": 1,
  "slug": "acme",
  "name": "Acme Corporation",
  "status": "pending",
  "tier_id": 1
}

Note that the organization status is pending - new organizations require platform owner approval.

5.3. Approve the Organization

As the platform owner, approve the newly created organization:

curl -X PUT http://localhost:3000/api/platform/organizations/acme/approve \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": 1,
  "slug": "acme",
  "name": "Acme Corporation",
  "status": "active"
}

The organization is now active and ready to use.

Next Steps

AuthOS is now fully operational. You can:

  1. Configure Organization OAuth Providers: Add GitHub, Google, or Microsoft OAuth credentials for your organization to enable end-user authentication (BYOO - Bring Your Own OAuth)
  2. Create Services: Register services that will use AuthOS for authentication
  3. Invite Team Members: Add organization administrators and members
  4. Integrate with the API: Review the Authentication Reference to integrate your applications

Additional Resources

Troubleshooting

Common Issues

1. Port Conflicts If port 3000 is already in use:

  • Edit .env and change SERVER_PORT=3000 to another port (e.g., 3001)
  • Map the new port in docker-compose.yml: 
    ports:
  - "3001:3000"

2. Database Locked (SQLite) If you see database is locked errors:

  • Ensure no other process (like a DB viewer) is holding a lock on data/sso.sqlite
  • Restart the container: docker-compose restart sso-sqlite

3. “Key not found” / JWT Errors

  • Verify rsa_private.pem exists in the keys/ directory
  • Ensure kid in the token matches the active key in the database
  • Run the setup script again if keys are missing: ./scripts/setup.sh

4. OAuth Redirect Mismatch

  • Error: redirect_uri_mismatch
  • Fix: Ensure PLATFORM_GITHUB_REDIRECT_URI in .env matches exactly what is configured in GitHub App settings
  • Development URL: http://localhost:3000/auth/admin/github/callback

Docker Permission Errors

If you encounter permission denied errors with Docker volumes:

# Fix ownership of data directory
sudo chown -R $USER:$USER data/
sudo chown -R $USER:$USER keys/