Getting Started

This page gets you oriented: the two integration patterns, how to pick one, and what you need before wiring up an app.

The API base URL

Every SSO API request goes to one host:

Production:   https://sso.aetherlabs.agency
Local dev:    http://localhost:4000

The other surfaces you will interact with:

Login / consent UI:  https://accounts.aetherlabs.agency   (local: http://localhost:3001)
Profile UI:          https://myaccount.aetherlabs.agency   (local: http://localhost:3002)
SSO admin console:   https://admin.sso.aetherlabs.agency    (local: http://localhost:3003)

Step 1 — Choose your integration pattern

Pattern A — First-party cookie SSO

Use this for Aether Labs-owned apps under the same parent domain, e.g. admin.aetherlabs.agency, myaccount.aetherlabs.agency, billing.aetherlabs.agency.

• No OAuth client, no client_secret, no PKCE.
• The app checks the session by calling GET /api/auth/me with cookies.
• Unauthenticated users are redirected to the login UI and sent back afterwards.

Simplest option. → Same-domain SSO guide

Pattern B — OAuth client

Use this for third-party apps, apps on unrelated domains, or apps that need an explicit consent screen.

• Register an OAuth client and get a client_id / client_secret.
• Run the standard OAuth 2.0 authorization-code flow.
• PKCE with S256 is required, and the client authenticates at the token endpoint with its secret (HTTP Basic or the request body).
• Browser-only apps cannot keep a secret, so they run the code exchange on their own backend.

→ OAuth integration guide

Step 2 — Gather what you need

• The API base URL — https://sso.aetherlabs.agency.
• The login UI URL — https://accounts.aetherlabs.agency.
• For Pattern A backends that verify tokens locally: the shared JWT_ACCESS_SECRET, plus the issuer (aetherlabs-sso) and audience (aetherlabs).
• For Pattern B: an OAuth client (client_id, client_secret) and a registered redirect URI.

Step 3 — Register your app

First-party apps (Pattern A)

Ask the Aether Labs SSO admin to add your app's origin to the API's ALLOWED_ORIGINS so the browser can send cookies and CORS does not block the call. In production COOKIE_DOMAIN=.aetherlabs.agency, so every *.aetherlabs.agency subdomain shares the session automatically.

OAuth clients (Pattern B)

Create a client from the SSO admin console (admin-web → OAuth clients), or with POST /api/admin/oauth-clients. Set:

Name:         Your Product
Redirect URI: https://yourapp.example.com/oauth/callback
Scopes:       openid profile email
Active:       true

Copy the client_id and client_secret. The secret is returned only once — store it on your backend, never in frontend code. Rotate it later with POST /api/admin/oauth-clients/:clientId/rotate-secret.

Step 4 — Implement the flow

Follow the guide for your pattern end to end:

• Same-domain SSO — auth guard, redirect contract, backend token verification, logout.
• OAuth integration — authorize redirect, PKCE, token exchange, refresh, revoke.

Then use the API reference for exact request and response shapes.

Verify your integration

# Is the API up?
curl -s https://sso.aetherlabs.agency/health

# Who am I? (with the access-token cookie, or a Bearer token)
curl -s https://sso.aetherlabs.agency/api/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Next steps

• Same-domain SSO guide
• OAuth integration guide
• Roles & permissions
• API reference