Connected services

Connected services let you store provider credentials once in Happier and then reuse them across supported backends and sessions.

They are different from provider authentication in provider settings:

• Connected services are stored in Happier and can be reused across compatible backends
• Provider authentication reflects the native login state of a provider CLI on one specific machine

See Provider authentication.

They exist so you can:

• connect subscriptions and API keys without manually re-entering them for every backend
• keep credentials encrypted in Happier Cloud and decrypt them only on the client / daemon
• choose per-service auth at session start instead of relying only on each backend's native auth
• monitor usage / quota snapshots for supported services
• make multi-machine workflows easier when the target machine should reuse the same Happier-managed credential

What a connected service is

Happier models different credential types as distinct connected services:

• openai-codex: OpenAI Codex subscription auth
• openai: OpenAI API key auth
• claude-subscription: Claude subscription auth
• anthropic: Anthropic API key auth
• gemini: Gemini OAuth auth

This split is intentional. Subscription auth and API-key auth have different provider behavior, billing paths, and backend materialization requirements, so Happier does not merge them into a single generic "Claude" or "OpenAI" credential type.

Where you manage them

In the app:

• Settings -> Connected services

From there you can:

• add one or more profiles for the same service
• give profiles custom labels
• set a default profile per service
• inspect profile details such as provider email, account id, and quota meters
• disconnect individual profiles

In the CLI:

• happier connect status
• happier connect codex ...
• happier connect claude ...
• happier connect gemini

Connection methods

OpenAI Codex

Supported methods:

• device code
• paste redirect URL
• in-app browser on native only

OpenAI Codex can also be connected with an API key, but that is modeled as the separate openai service.

OpenAI API key

Supported methods:

• manual API key entry

Use this when you want OpenAI-backed backends to run against your own API key instead of your Codex subscription login.

Claude subscription

Supported methods:

• setup-token
• paste redirect URL
• in-app browser on native only

Setup-token is the recommended default. Generate it on any machine already logged into Claude Code:

claude setup-token

Then paste it into Happier.

Anthropic API key

Supported methods:

• manual API key entry

This is the Anthropic Console API-key path. It is separate from claude-subscription.

Gemini

Supported methods:

• paste redirect URL
• in-app browser on native only

Why web behaves differently

Happier does not use embedded OAuth capture on web. Web falls back to paste-based flows because a browser app cannot reliably auto-capture provider redirects to localhost.

Backend compatibility

Connected services are not global "works everywhere" credentials. Each backend declares which service ids and credential kinds it can consume.

Important limitations:

• OpenCode does not currently accept claude-subscription.
• Pi accepts claude-subscription only when the profile is a setup-token profile, not a Claude OAuth profile.
• anthropic is API-key only in Happier.

Using connected services in the new-session flow

If the selected backend supports connected services, the new-session screen shows an auth picker.

That picker is dynamic:

• it appears only for backends that support connected services
• it shows only services compatible with the selected backend
• it shows only connected profiles that are valid for that backend
• it lets you choose native auth or connected auth for each compatible service

If no compatible connected profile exists for a service, Happier keeps that service on native auth and offers a shortcut to open Connected services settings.

Connected services and browsing sessions (Codex)

For some providers, your connected-service choice affects which provider “home” Happier should use for session browsing.

The most important example is Codex:

• With native auth, Happier browses sessions from the machine’s standard Codex home.
• With a connected service profile selected for Codex, Happier browses sessions from that connected-service-backed Codex home.

This matters in two places:

• Direct → Browse provider sessions: you can explicitly choose a source/home when browsing.
• Resume ID browse: the picker is locked to the effective Codex home implied by your new-session selection so the chosen session can actually be resumed under that auth.

If you need to browse a different Codex home, switch the auth choice first and then browse again.

Connected services and session handoff

Connected services are often the easiest way to preserve session continuity across machines.

Why:

• the credential is stored in Happier, not only in one machine-local provider login
• compatible backends can materialize that credential again on another machine
• you can hand off the same Happier session and continue without depending only on native provider CLI auth on the destination

This is especially useful for:

• moving a session from one desktop/laptop to another
• moving between a host machine and a VM
• keeping continuity when only one side had previously been set up through the app

Connected services do not replace every native provider login flow. Some providers and runtimes still depend on machine-local authentication. But for supported backends, connected services are the preferred path for cross-machine continuity.

See:

• Session handoff
• Provider authentication

Profiles, defaults, and labels

Each connected service can have multiple profiles, for example:

• a personal OpenAI subscription and a work OpenAI subscription
• multiple Anthropic API keys
• multiple Claude setup-token profiles

For each service you can:

• set one default profile
• override the default at session start
• assign a friendly label so the auth picker can show something clearer than just work or default

Quotas

Quota / usage surfaces are behind the connectedServices.quotas feature gate.

Current quota snapshots are available for:

• openai-codex
• claude-subscription
• gemini

They appear in:

• the Connected services list as badges on the effective profile
• per-profile detail screens
• the new-session auth picker for connected profiles

Each profile detail view lets you:

• refresh the snapshot
• inspect the provider plan label when available
• pin specific meters so the same meters appear as summary badges elsewhere in the UI

Security model

For OAuth-based services, Happier clients do not exchange provider codes for tokens directly.

Instead:

1. the client receives an OAuth code through device auth, paste, or embedded browser capture
2. the client calls Happier server /v2/connect/<serviceId>/oauth/exchange
3. the server exchanges the code with the provider
4. the server returns an encrypted bundle sealed to the client public key
5. the client decrypts the bundle locally and stores the resulting credential record

This keeps provider secrets, including server-side OAuth client secrets, out of the UI bundle.

When a session starts, the daemon decrypts the selected records locally and materializes only the backend-specific auth it needs for that spawn.

Feature gates and overrides

Connected services uses the canonical feature-gating system.

Server feature flags:

• connectedServices
• connectedServices.quotas

UI build gates:

• EXPO_PUBLIC_HAPPIER_FEATURE_CONNECTED_SERVICES__ENABLED
• EXPO_PUBLIC_HAPPIER_FEATURE_CONNECTED_SERVICES_QUOTAS__ENABLED

See:

• Server feature flags
• App environment variables (Expo)

Advanced server overrides

Most users should not need these. They are mainly for self-hosted deployments and drift reduction.

Global server exchange timeout:

• HAPPIER_CONNECTED_SERVICES_OAUTH_EXCHANGE_TIMEOUT_MS

OpenAI Codex OAuth:

• HAPPIER_CONNECTED_SERVICES_OPENAI_CODEX_OAUTH_CLIENT_ID
• HAPPIER_CONNECTED_SERVICES_OPENAI_CODEX_OAUTH_TOKEN_URL

Gemini OAuth:

• HAPPIER_CONNECTED_SERVICES_GEMINI_OAUTH_CLIENT_ID
• HAPPIER_CONNECTED_SERVICES_GEMINI_OAUTH_CLIENT_SECRET
• HAPPIER_CONNECTED_SERVICES_GEMINI_OAUTH_TOKEN_URL

Claude subscription OAuth:

• HAPPIER_CONNECTED_SERVICES_CLAUDE_SUBSCRIPTION_OAUTH_CLIENT_ID
• HAPPIER_CONNECTED_SERVICES_CLAUDE_SUBSCRIPTION_OAUTH_TOKEN_URL

Quota fetchers:

• HAPPIER_CONNECTED_SERVICES_QUOTAS_STALE_AFTER_MS
• HAPPIER_CONNECTED_SERVICES_QUOTAS_USER_AGENT
• HAPPIER_CONNECTED_SERVICES_OPENAI_CODEX_USAGE_URL
• HAPPIER_CONNECTED_SERVICES_CLAUDE_SUBSCRIPTION_USAGE_URL
• HAPPIER_CONNECTED_SERVICES_ANTHROPIC_USAGE_URL

HAPPIER_CONNECTED_SERVICES_ANTHROPIC_USAGE_URL remains accepted as a fallback override for Claude subscription quota fetching, but the primary service identity is claude-subscription.