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
• github: GitHub token auth for source-control workflows

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.

GitHub is the first connected service that is not an agent/backend credential. It is used by source-control features such as GitHub repository publishing and GitHub pull request operations.

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

GitHub

Supported methods:

• token / Personal Access Token entry
• local GitHub CLI auth outside Connected services

A connected GitHub token lets Happier use GitHub REST APIs for:

• publishing a local repository to GitHub
• listing and opening pull requests for the current branch
• creating or reusing pull requests

The local gh CLI is not stored as a connected service. If gh is already installed and authenticated with gh auth login, Happier can use it as an optional fallback for GitHub source-control workflows.

Current GitHub OAuth note:

• GitHub OAuth/device flow is not enabled in this build.
• Use a GitHub token in Connected services, or authenticate the local gh CLI.

GitLab is not currently a connected service in Happier. GitLab merge-request workflows use an authenticated local glab CLI when available, or a no-auth compare URL fallback.

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 accepts claude-subscription only when the profile is a setup-token profile, not a Claude OAuth profile.
• Pi accepts claude-subscription OAuth and setup-token profiles. Claude subscription OAuth is materialized into Pi's isolated auth.json; setup-token profiles are materialized as Pi API-key credentials.
• anthropic is API-key only in Happier.
• github is not consumed by agent backends. It is consumed by source-control workflows.

Source-control compatibility

This means a user who already has gh installed and authenticated can use GitHub PR/publish features without connecting GitHub in Happier first. Connecting GitHub is still the preferred cross-machine path because the credential can be reused by the daemon on the target machine.

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.
• Browse sessions: the picker is locked to the effective Codex home implied by your new-session selection, so the session you choose is one that can actually resume 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

Account pools

A pool groups several accounts for the same service and decides which one should be handling work right now. It is the answer to running out of quota mid-turn: instead of the session stopping until a reset, the pool moves to another account and carries on.

Pools are shared by every session using them. When one session discovers the active account is exhausted, the pool selects a replacement and the other sessions bound to that pool adopt it, rather than each rediscovering the same dead account.

Choosing which account is active

Reorder members to set the fallback order, and enable or disable individual accounts without removing them.

When it switches

Automatic switching is off by default — turn it on per pool. Once on, it reacts to:

It can also move before a hard limit: when the active account drops below 15% remaining and a better member is available. That threshold is configurable.

Bounds that stop it thrashing

A broken pool or a repeated authentication failure must not become a switching loop, so switching is bounded:

• at most 1 switch per turn
• at most 3 switches per session per hour
• a 30-second cooldown between switches
• provider reset times are honoured, so a member known to be resetting shortly is not treated as permanently dead

Recovery after a hard limit

When a session does hit a wall, what happens next is configurable:

When it resumes, it can send Happier's standard continuation prompt, a prompt you write, or nothing at all.

Freshness

Quota snapshots older than five minutes are re-probed before a turn. By default Happier probes only when the snapshot is stale, checking the current account first and candidates after — you can make it probe every turn, or never, and reverse that order.

Quotas

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

Current quota snapshots are available for:

• openai-codex
• claude-subscription
• gemini

GitHub connected accounts do not currently expose quota meters in Happier.

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

When you hit a usage limit

Reaching a provider's usage limit does not silently stall the session. Happier shows a banner explaining what it is waiting for and what you can do about it, with a status of Limit reached, Temporarily throttled, or Ready to resume.

What it offers depends on what is actually possible:

Always wait and resume remembers your choice for that account so the banner stops asking, and Ask each time puts the question back.

Usage-reset credits

Some Codex accounts receive usage-limit reset credits from the provider. Where they exist, the banner says how many are available and when the next one expires, and Apply reset consumes one without leaving Happier — no separate account page, no session restart.

Happier reports back what actually happened rather than assuming success: the reset applied, there was nothing to reset, no credit remained, or the credit had already been used. A blocked session continues once the provider starts accepting requests again.

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.

Token-based services, including GitHub token profiles, are stored as connected-service credentials and decrypted only where the client/daemon needs to use them. They do not require Happier to run a GitHub OAuth application in the current build.

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.