Authentication

Overscore uses a layered authentication model. You sign in with Google to access the Hub, and deployed dashboards are protected by a separate Cloudflare Worker auth layer that keeps your data secure.

Google OAuth (Hub access)

The Hub at overscore.dev uses Google OAuth via Supabase for authentication. When you click Sign in with Google, here's what happens:

  1. You're redirected to Google's OAuth consent screen
  2. After granting access, Google sends an auth code back to the Hub
  3. Supabase exchanges the code for a session token
  4. The session cookie is stored in your browser

You stay signed in until you explicitly log out or the session expires. No passwords to manage — your Google account is your identity.

Member roles

Every project has team members with one of three roles:

| Role | Permissions | |------|-------------| | Owner | Full control — manage members, connections, dashboards, billing. One per project. | | Admin | Add/remove members, deploy dashboards, manage BigQuery connections and queries. | | Viewer | View deployed dashboards and query results. Cannot deploy or change settings. |

To invite a team member, go to your project's Members tab and add them by email. They'll need to sign in with Google on their first visit.

Dashboard authentication (Worker layer)

When someone visits a deployed dashboard (e.g., acme.overscore.dev/sales-dashboard/), the Cloudflare Worker serving that dashboard checks authentication before returning any content:

  1. The Worker checks for a valid session cookie
  2. If the user isn't signed in, they're redirected to the Google OAuth flow
  3. After sign-in, the Worker verifies the user is a member of that project
  4. Only then is the dashboard HTML, JS, and data served

This means your dashboards are private by default. Only team members with access to your project can view them.

API keys

API keys authenticate programmatic requests to the query API from your deployed dashboards. Each project has an API key that the @overscore/client package uses behind the scenes.

How API keys work

When you deploy a dashboard, the CLI bakes your project's API key into the build. The OverscoreProvider component sends this key with every query request:

{
  "projectSlug": "acme",
  "dashboardSlug": "sales-dashboard",
  "queryName": "revenue_by_month",
  "apiKey": "os_live_abc123..."
}

The server validates the API key, confirms the query is registered to that project, and returns the results.

Managing API keys

You can view and regenerate your project's API key from the Settings tab in the Hub. If you regenerate a key, you'll need to redeploy your dashboards for them to pick up the new key.

Keep your API keys secret. They grant access to execute any registered query in your project. Never commit them to a public repository — use environment variables instead.

Auth flow summary

Here's how the different auth mechanisms fit together:

  • Hub access — Google OAuth session cookie, managed by Supabase
  • Dashboard viewing — Cloudflare Worker checks session cookie + project membership
  • Query execution — API key in request body, validated server-side
  • CLI deployment — Session token from overscore login, passed as a bearer token

Environment variables

The key auth-related environment variable for your dashboard project:

VITE_OVERSCORE_API_KEY=os_live_abc123...

This is set automatically by npx create-overscore and read by Vite at build time.

Next steps