Skip to content

Quickstart

This guide assumes you have completed the Installation steps. You will configure an OAuth provider, register client and service apps, and verify the full auth flow.

1. Configure an OAuth Provider

You need at least one OAuth provider for user authentication. Google is the easiest to get started with.

  1. Go to the Google Cloud Console.
  2. Create an OAuth 2.0 Client ID (application type: Web application).
  3. Add http://localhost:9003/auth/callback/google as an Authorized redirect URI.
  4. Copy the client ID and secret into your .env:
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Other providers

GitHub and Microsoft EntraID are also supported. See the Configuration reference for their environment variables. You can enable multiple providers simultaneously.

2. Set the Session Secret

The service uses server-side sessions for the OAuth flow. Generate a secure secret:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Paste the output into your .env:

SESSION_SECRET_KEY=your-generated-secret-here

Docker users

If you followed the Docker installation path, you already generated this in step 3 of the installation.

Do not skip this in production

The default value (dev-only-change-me-in-production) is intentionally insecure. Always set a unique, random secret for any non-local environment.

3. Start the Service

If you followed the Docker installation, the service is already running. After updating your .env with OAuth credentials, restart to pick up the changes:

docker compose -f docker-compose.prod.yml up -d

make start

This runs the FastAPI application with hot-reload on port 9003. Database migrations are applied automatically on startup.

Verify it's running:

curl http://localhost:9003/health

4. Access the Admin Panel

The admin panel is built into the Sentinel container and served at the same port:

Open http://localhost:9003/admin in your browser.

Start the admin panel separately:

make admin

Then open http://localhost:9004.

Admin access

Your email must be listed in the ADMIN_EMAILS environment variable (comma-separated) to access the admin panel. You can also promote a user with make create-admin (from-source only).

Sign in through the admin panel using your OAuth provider to create your initial user account.

5. Register a Client App

Every frontend that authenticates through Sentinel must be registered as a client app with its redirect URI(s). This prevents unauthorized apps from initiating OAuth flows.

  1. Navigate to Client Apps in the sidebar.
  2. Click Add Client App.
  3. Set a name (e.g., dev-frontend) and add the redirect URI: http://localhost:9003/docs.
  4. Save.
curl -X POST http://localhost:9003/admin/client-apps \
  -H "Content-Type: application/json" \
  -H "Cookie: admin_token=YOUR_ADMIN_TOKEN" \
  -d '{"name": "dev-frontend", "redirect_uris": ["http://localhost:9003/docs"]}'

Why client apps?

Client apps control the redirect URI allowlist. Sentinel will reject any redirect_uri that doesn't match a registered client app. This protects against open-redirect attacks.

6. Register a Service App

If your backend needs to call Sentinel's API (for permissions, roles, or resource registration), register a service app to get an API key.

  1. Navigate to Service Apps in the sidebar.
  2. Click Add Service App.
  3. Set a name and toggle Dev Mode on for local development.
  4. Copy the generated sk_... key — you'll need it for your backend's .env.

Service apps vs. the old SERVICE_API_KEYS

Service apps are managed in the database through the admin panel. The SERVICE_API_KEYS environment variable is deprecated and only used as a fallback during migration.

7. Verify the Auth Flow

Navigate to the login endpoint with the redirect URI you registered:

http://localhost:9003/auth/login/google?redirect_uri=http://localhost:9003/docs

This redirects you to Google's consent screen. After you authorize, the service creates a user record (if it's your first login) and redirects to your redirect_uri with an authorization code (?code=X).

Exchange it for JWT tokens:

curl -X POST http://localhost:9003/auth/token \
  -H "Content-Type: application/json" \
  -d '{"code": "CODE_FROM_REDIRECT", "workspace_id": "YOUR_WS_ID"}'

8. Explore the API

Open the interactive Swagger UI:

http://localhost:9003/docs

This documents every endpoint, including auth flows, user management, workspace operations, group management, and the permission system.

Optional: Seed Data

Load test data to explore the API without manually creating resources:

docker compose -f docker-compose.prod.yml exec sentinel python -m scripts.seed

make seed

This populates the database with sample users, workspaces, groups, and permissions.

Try the Demo App

The repository includes a complete demo application ("Team Notes") that showcases JWT auth, workspace roles, entity ACLs, and custom RBAC with a React frontend using @sentinel-auth/react and a FastAPI backend.

Prerequisites

Before the demo app can authenticate, register a client app with redirect URI http://localhost:9101/auth/callback (see step 5 above) and a service app for the demo backend (see step 6).

# Clone the repo if you haven't already
git clone <repo-url> identity-service && cd identity-service

# Demo backend
cd demo/backend && uv sync && uv run python -m src.main

# Demo frontend (in another terminal)
cd demo/frontend && npm install && npm run dev

Open http://localhost:9101 and sign in with Google. See the Tutorial for a detailed walkthrough of how the demo is built.

Next Steps

  • Review all available settings in the Configuration reference.
  • Read the Architecture section to understand how the service is structured.
  • Follow the Tutorial to build your own app with the SDK.
  • Integrate your application using the SDK guide.