Authentication

Guide 6 min read Updated May 2026

GrooveOS signs you in with GitHub. The same "Sign in with GitHub" button works on the web app at grooveos.app, in the Chrome extension popup, and in any other GrooveOS surface — they all share the same identity. There is no password to manage.

Behind the scenes GrooveOS uses a GitHub App (the modern successor to OAuth Apps). The difference matters: the GitHub App can be installed on your GitHub organization once, which then lets any org member join your GrooveOS team automatically — no manual invites needed.

The basic flow is the same everywhere:

Click Sign in with GitHub.
GitHub shows a consent screen the first time. Approve xbrain.
You land back on GrooveOS, signed in. Your GitHub avatar and username appear in the top bar.

Where you sign in	Button location
Web app	grooveos.app/account/teams/ — primary button
Chrome extension	Extension popup — first launch
LibreChat	chat.grooveos.app — "Sign in with GitHub" on the login screen

Same GitHub account everywhere

The web app, the Chrome extension, and LibreChat all sign in against the same GitHub App, so your GrooveOS identity is consistent across surfaces. Tokens you create in one surface (e.g. an xbt_ API token from the web app) work in all of them.

Installing xbrain on your org

If you sign in for the first time and your primary GitHub organization hasn't installed the xbrain App yet, GrooveOS shows a yellow banner like:

Install xbrain on `your-org-name`
[ Install xbrain on org → ]

What happens next depends on your role inside the GitHub org:

You are a GitHub org owner / admin. Click the button. GitHub asks you to choose which repos xbrain can see (you can pick "All repositories" or a subset — xbrain doesn't actually need any repo access for sign-in, only the org membership read). Approve. GitHub sends you back to GrooveOS, and the rest of your org can now sign in.
You are a regular member of the org. Click the button. GitHub will show an "Approval required" page that lets you request the install. Once an owner approves, every org member can sign in.

The install is per-org, not per-user

Once xbrain is installed on your GitHub org, no other member of that org needs to do it again. They just click "Sign in with GitHub" and they're in. The install is what unlocks the auto-join behaviour below.

Auto-join via GitHub org

Every xbrain team can declare a github_org field in its settings. When you sign in with GitHub, GrooveOS reads the list of organizations you belong to, and adds you to every team whose github_org matches one of your orgs — no manual invite needed.

This is the default way to add people to a team:

Team admin sets github_org = your-org in team settings.
Anyone in your-org signs in with GitHub for the first time.
GrooveOS detects the org match and auto-adds them to the team as a Member.
Team admins receive an email titled "New member auto-joined <team>".

If an auto-join is unexpected, an admin can block the user from the team — see Blocking members below.

Tokens & refresh

Once you're signed in, GrooveOS gives you an xbt_ personal API token. This is what every GrooveOS surface uses under the hood to call the API on your behalf:

xbt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

You can list, name, and revoke your xbt_ tokens from your profile page. See the API Reference for the full programmatic surface — xbt_ tokens are how you build your own scripts and integrations.

Behind the scenes: GitHub tokens

In addition to the xbt_ token, GrooveOS stores two GitHub-side tokens for your account:

Token	Lifetime	Why
User access token (`ghu_`)	8 hours	Used to look up your GitHub profile, verified emails, and org memberships when you sign in.
Refresh token (`ghr_`)	6 months	Single-use; quietly rotates the 8h access token in the background so you don't have to re-sign-in every workday.

You don't see these — they're managed for you, encrypted at rest, and rotated automatically. After 6 months of no GrooveOS activity the refresh token expires; on your next visit you click "Sign in with GitHub" again and the cycle restarts.

Blocking members

Team admins can block any member at any time from the Settings card on the teams page or from the Options tab of the Chrome extension. Blocked users immediately stop having access:

Every team-scoped API call returns HTTP 403 — even with a valid xbt_ token created before the block.
The block survives sign-out / sign-in. The user cannot recover access by re-authorizing GitHub.

Pre-blocking a GitHub login

Admins can also pre-block a GitHub username that hasn't signed up yet. The next time that user signs in via your org, the auto-grant pipeline checks the pre-block list before adding them to the team. They will sign in successfully but won't be auto-joined.

Permissions xbrain requests

When you authorize xbrain via GitHub, the App asks for:

Email addresses (read-only) — to attach your verified email to your user row so admins can invite you and notifications reach you.
Members (read-only) — so xbrain can read which orgs you belong to and apply the auto-join rule.

That's it. xbrain does not request repo content access, write access to your account, or any permissions on your code. You can review the install at any time on GitHub: github.com/settings/installations (personal) or github.com/organizations/<your-org>/settings/installations (org).

Revoking access

To cut all GrooveOS access from your GitHub account, uninstall the xbrain App from GitHub's installation settings. GrooveOS detects the uninstall via webhook and your team memberships become read-only until the App is reinstalled.

Troubleshooting

Symptom	What's happening	Fix
"Install xbrain on org" banner doesn't go away after install	GitHub's install webhook hasn't reached GrooveOS yet (usually < 5 s).	Wait a few seconds and refresh the page. GrooveOS also self-heals on the next sign-in by querying GitHub directly.
Approval required after clicking Install	You're a regular member of the org, not an owner.	An org owner has to approve the install request. Ask them, then come back and sign in again.
Signed in, but no teams listed	Your org isn't tied to any GrooveOS team yet, or you're in a private org GrooveOS can't see without the install.	Ask a team admin to either invite you by email or set `github_org` on the team to your org.
HTTP 401 unauthorized from the API	Your refresh token expired (no GrooveOS activity in 6 months) or your `xbt_` was revoked.	Sign in with GitHub again. If your `xbt_` was revoked, mint a new one from your profile.
HTTP 403 with "Member blocked from team …"	A team admin blocked you.	Contact the admin. Re-signing-in won't help — the block is server-side.

What's next

Onboarding Guide — Step-by-step from sign-in to a working Claude.ai / ChatGPT integration.
Teams & Projects — Setting github_org, inviting members, project scopes.
API Reference — Using your xbt_ token programmatically.