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 16, 2025
Edit on GitHub
getting-started setup local-development oauth

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

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