ALEX STUDIO HQ / DOCUMENTATION

One Google login.
All your projects.

Configure a project key

Enable auth on your project.
Under Projects, manage the project and select auth.
Create a key with auth permission.
Existing keys do not automatically gain new permissions.
Open Google sign-in on that key.
Add your exact callback URL, enable sign-in, and copy its public client ID. Up to 10 callbacks are supported. Production callbacks use HTTPS; HTTP is allowed only on localhost or loopback IPs.

Start sign-in from your app’s backend

const login = await hq.auth.start({
  clientId: "acl_YOUR_PUBLIC_CLIENT_ID",
  redirectUri: "https://your-app.example/auth/callback",
});

// Store these in your app’s server-side session:
session.oauthState = login.state;
session.codeVerifier = login.codeVerifier;

// Redirect the browser to login.url.

The public client ID is safe to expose. Your project API key and PKCE verifier must remain on your app’s backend. Store the state and verifier in a short-lived server-side session or authenticated, encrypted HttpOnly cookie. Do not use a shared global variable.

Handle your app’s callback

const tokens = await hq.auth.exchange({
  clientId: "acl_YOUR_PUBLIC_CLIENT_ID",
  redirectUri: "https://your-app.example/auth/callback",
  callbackUrl: request.url,
  expectedState: session.oauthState,
  codeVerifier: session.codeVerifier,
});

// Delete the temporary state/verifier after the exchange.
// Store tokens.access_token in your app’s protected server session.
// Use tokens.user.id as the ecosystem user identity.

const { user } = await hq.auth.user({
  clientId: "acl_YOUR_PUBLIC_CLIENT_ID",
  accessToken: tokens.access_token,
});

// On logout, revoke the ecosystem token too:
await hq.auth.revoke({
  clientId: "acl_YOUR_PUBLIC_CLIENT_ID",
  accessToken: tokens.access_token,
});

One Google callback

Google continues to return to https://admin.alexstudiohq.com/auth/callback. The gateway keeps owner administration and shared user sign-in in separate flows. Ordinary app callbacks are registered here, not added to Google Console.

Your existing Google OAuth consent-screen rules still apply. If the Google app is in testing, its permitted test-user list may restrict who can sign in. Google verification or credential rotation may still require Console access.

Security and lifetime

External callbacks receive a single-use authorization code, never a Google token. Codes expire after 60 seconds; login requests expire after 5 minutes. Both the application flow and upstream Google flow use S256 PKCE. Callback URLs must match an explicit registered URL.

Opaque user access tokens expire after one hour and are bound to the exact project key and client. Disabling a client, revoking its project key, pausing its project, or blocking a user prevents access. Changing callback settings invalidates that client’s pending requests, codes, and sessions. Google access tokens are used only to verify identity and are not stored or returned to projects.

A user ID is shared across your ecosystem, while sessions and project membership remain scoped. A user token does not grant database or administrator access. This release exposes a custom shared sign-in API; it is not an OpenID Connect provider and has no refresh tokens, ID tokens, or JWKS endpoint.

HTTP API

GET /identity/authorize accepts response_type=code, client_id, redirect_uri, state, code_challenge, and code_challenge_method=S256. State must contain 32–256 URL-safe characters. The PKCE challenge is a base64url-encoded SHA-256 digest.

POST /v1/auth/token exchanges { clientId, redirectUri, code, codeVerifier }. POST /v1/auth/user and POST /v1/auth/revoke accept { clientId, accessToken }. All three require your project’s Bearer API key with auth permission and record request activity. SDK exchange also validates the callback state locally.

Shared sign-in starts are limited to 20 per five minutes per source IP, at most 200 per client per UTC day, and 500 per account per UTC day. These limits keep the initial free-plan rollout bounded.

One Google login.All your projects.