Auth Model

Open Spanner separates dashboard login from service authentication. People sign in through the dashboard; backend services, SDKs, workers, and scripts use API keys.

Dashboard Sign-In

Dashboard users can sign in with email and password. Deployments can also enable OAuth providers for the dashboard. Open Spanner currently ships with:

• Google OAuth/OIDC
• GitHub OAuth

Social login maps external accounts into Open Spanner users through provider identities. The internal user remains the canonical dashboard user, while each social account is linked by provider and provider subject. If a verified social email matches an existing dashboard user, Open Spanner links that provider identity to the existing user instead of creating a duplicate.

Social login only creates dashboard sessions. It does not create API keys, bypass API key scopes, or change service authentication.

New account creation is enabled by default. To close registration, create the intended dashboard users and then set OPEN_SPANNER_REGISTRATION_ENABLED=false before restarting the API. This removes registration from the dashboard and blocks both new password users and new users created through OAuth. Existing users continue to sign in, and a verified OAuth identity may still link to an existing user with the same email.

Workspaces

Each dashboard user works inside a workspace. Meters, usage events, subjects, plans, alert rules, alert destinations, export jobs, saved queries, and API keys are scoped to that workspace.

This means two dashboard users can use the same Open Spanner deployment without seeing each other's metering data. A user only sees the meters, usage, plans, alerts, exports, and keys that belong to their current workspace.

API keys inherit the workspace where they were created. When a backend service sends usage with an API key, Open Spanner writes and reads data in that key's workspace. The service does not send a workspace ID in each request.

Every account starts with a personal workspace. Owners can invite other registered users as admins or viewers, and members can switch between every workspace they belong to. Roles are enforced for both dashboard sessions and API keys created in the shared workspace. See Workspace Access for the permission model, secure invitation lifecycle, and workspace switching.

Use separate workspaces when you want hard separation between environments, customers, or internal teams. Use separate API keys inside a workspace when you want different backend services to have different permissions.

Social Login Configuration

OAuth providers all use the same configuration shape:

OPEN_SPANNER_<PROVIDER>_OAUTH_ENABLED
OPEN_SPANNER_<PROVIDER>_OAUTH_CLIENT_ID
OPEN_SPANNER_<PROVIDER>_OAUTH_CLIENT_SECRET
OPEN_SPANNER_<PROVIDER>_OAUTH_REDIRECT_URL

For the built-in providers, <PROVIDER> is GOOGLE or GITHUB.

Providers are shown on the login page only when both conditions are true:

• The provider is enabled with OPEN_SPANNER_*_OAUTH_ENABLED=true.
• The provider has a client ID and client secret.

Use these flags to hide or disable providers without deleting their credentials:

OPEN_SPANNER_GOOGLE_OAUTH_ENABLED=false
OPEN_SPANNER_GITHUB_OAUTH_ENABLED=true

The login page reads /v1/auth/providers and only shows enabled providers.

OAuth callbacks use the provider ID in the route:

/v1/auth/oauth/google/callback
/v1/auth/oauth/github/callback

API Keys

Authorization: Bearer <api_key>

Create API keys from the dashboard. Copy them when they are created; the full key is not shown again.

Rotate keys from the dashboard or POST /v1/auth/api-keys/{id}/rotate. The replacement preserves the old key's name, scopes, allowed meters, and expiry. Choose a grace period from zero to 24 hours: both credentials work during the grace period, then the old key is rejected. You can revoke a key immediately at any point with DELETE /v1/auth/api-keys/{id}.

Open Spanner retains revoked key metadata and an immutable lifecycle history for creation, rotation, and revocation. The full secret is never stored in the audit log. Read the history from GET /v1/auth/api-key-events or the API Keys dashboard.

API keys should be used from trusted server-side code. Do not put Open Spanner API keys in browser or mobile clients.

Scopes And Meter Access

API keys can be limited by operation and by meter name. Use scopes to decide what a backend service can do, then optionally set an allowed meter list when the key should only work for specific meters.

Common scopes:

• usage:write records usage events through REST or gRPC.
• usage:read queries usage buckets, dimensions, breakdowns, and raw events.
• meters:read reads meter definitions.
• meters:write creates or edits meter definitions.
• alerts:read and alerts:write manage alert rules and destinations.
• exports:read and exports:write download or queue usage exports.
• plans:read checks quota and reads plan progress.
• plans:write manages plans and subject assignments.
• system:read reads operational stats.
• system:write applies audited quota counter repairs.

Leave the allowed meter list empty when a trusted backend service should work across all meters. Add meter names when a key belongs to one service or pipeline.

Good starting points:

• Ingestion services usually need usage:write.
• Reporting services usually need usage:read, exports:read, and exports:write.
• Provisioning services that create meters need meters:read and meters:write.
• Feature-gating services usually need plans:read.
• Alert automation needs alerts:read and alerts:write.

Use the smallest set of scopes that matches the service. If a key only writes one meter, set both the scope and the allowed meter list.