Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Quickstart

Add authentication to your application in 5 minutes.

1. Create an Account

Sign up at your Aero2 dashboard to get started. After signing in, you'll land on the application list.

2. Create an Application

Click Create Application and enter a name (e.g., "My App"). Aero2 generates a random slug (e.g., swift-maple) that becomes your subdomain.

Your application will be available at https://{slug}.yourdomain.com.

3. Get Your API Keys

After creating the application, you'll receive two keys:

  • Publishable key (pk_live_...) — Safe for frontend code. Identifies your application.
  • Secret key (sk_live_...) — Server-side only. Shown once — copy it immediately.

4. Register an OAuth Client

Create an OAuth client for your application via the API:

curl -X POST https://{slug}.yourdomain.com/api/clients \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Web App",
    "redirect_uris": ["https://myapp.com/callback"]
  }'

Save the client_id and client_secret from the response.

5. Add Login to Your App

Redirect users to the authorization endpoint with PKCE:

// Generate PKCE values
const array = new Uint8Array(32);
crypto.getRandomValues(array);
const codeVerifier = base64UrlEncode(array);
 
const hash = await crypto.subtle.digest(
  'SHA-256',
  new TextEncoder().encode(codeVerifier)
);
const codeChallenge = base64UrlEncode(hash);
 
// Store for later
sessionStorage.setItem('code_verifier', codeVerifier);
 
// Redirect to Aero2
const params = new URLSearchParams({
  client_id: 'your-client-id',
  redirect_uri: 'https://myapp.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
  state: crypto.randomUUID(),
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
});
 
window.location.href =
  `https://{slug}.yourdomain.com/oauth2/authorize?${params}`;

6. Handle the Callback

On your callback page, exchange the authorization code for tokens:

const url = new URL(window.location.href);
const code = url.searchParams.get('code');
const codeVerifier = sessionStorage.getItem('code_verifier');
 
const response = await fetch(
  'https://{slug}.yourdomain.com/oauth2/token',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: 'https://myapp.com/callback',
      client_id: 'your-client-id',
      client_secret: 'your-client-secret',
      code_verifier: codeVerifier,
    }),
  }
);
 
const tokens = await response.json();
// tokens.access_token, tokens.id_token, tokens.refresh_token

7. Fetch User Info

Use the access token to get the authenticated user's profile:

const user = await fetch(
  'https://{slug}.yourdomain.com/oauth2/userinfo',
  {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
  }
).then(r => r.json());
 
// { sub: "...", name: "Jane Doe", email: "jane@example.com" }

Next Steps