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. | | Editor | Deploy dashboards, manage connections and queries, invite viewers. A billable seat. | | 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.

CLI authentication (device tokens)

Run npx @overscore/cli auth login once per machine. It opens a browser, you approve the request, and a device token (prefix ocli_) is saved to ~/.overscore/config. The CLI sends that token as Authorization: Bearer <token> on every request to the Hub.

  • npx @overscore/cli auth shows your current status
  • npx @overscore/cli auth logout removes the saved token

You can list and revoke your devices in the Hub at /settings/devices. There is nothing to copy or paste, and no API key to manage by hand.

Query authentication

Requests to the query API carry their credential in a header. Nothing secret goes in the request body.

Deployed dashboards

Deployed dashboards do not contain an API key. deploy runs the production build with VITE_OVERSCORE_API_KEY set to an empty string, so no key reaches the bundle.

In production the Cloudflare Worker serving the dashboard authorizes each query with an X-OS-Access-Token header. That token is derived from a signed os_access cookie (HMAC-SHA256, 7-day TTL, scoped to .overscore.dev) that the Hub sets after verifying the viewer's Supabase session. Access follows the viewer's identity rather than a shared secret.

Local development

overscore dev mints a short-lived API key (prefix os_) and injects it into the dev server as VITE_OVERSCORE_API_KEY. You never see or handle it. Vite exposes it to the running app, and @overscore/client sends it as Authorization: Bearer <key>.

The CLI does not read an OVERSCORE_API_KEY environment variable, and there is no screen in the Hub for generating or viewing a key.

Request shape

The request body is snake_case and carries no credential:

{
  "project_slug": "acme",
  "query_name": "revenue_by_month"
}

force_refresh and accept_arrow are optional booleans. The server validates the header, confirms the query is registered to that project, and returns the results.

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 — X-OS-Access-Token header in production, Authorization: Bearer with a short-lived os_ key in local dev
  • CLI — device token from overscore auth login, passed as a bearer token

Environment variables

There is one auth-related environment variable, VITE_OVERSCORE_API_KEY, and the CLI sets it at runtime. A scaffolded project's .env never contains it:

  • overscore dev sets it to a freshly minted short-lived key for the dev server
  • overscore deploy sets it to an empty string for the production build, so the key never ships

You don't need to set it yourself.

Next steps