> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0 login (Google & GitHub)

> Log in to ButterCMS using OAuth 2.0 social providers, including Google and GitHub.

OAuth 2.0 is an industry-standard authorization framework that allows you to sign in to ButterCMS using an existing account from a trusted third-party provider — no separate password required.

## Supported OAuth providers

<CardGroup cols={2}>
  <Card title="Google" icon="google">
    Sign in with any Google or Google Workspace account
  </Card>

  <Card title="GitHub" icon="github">
    Sign in with your GitHub personal or organization account
  </Card>
</CardGroup>

<Tip>
  ButterCMS also supports Heroku login via the [Heroku add-on](./heroku-add-on), which lets you access the ButterCMS dashboard directly from Heroku using SSO — no separate login required.
</Tip>

## How OAuth login works

When you choose to log in with Google or GitHub, ButterCMS never receives or stores your password. Instead, the provider authenticates you and issues a short-lived token that confirms your identity.

1. Click **Sign Up With Google** or **Sign Up With Github** on the [ButterCMS signup page](https://app.buttercms.com/join)
2. You are redirected to the provider's authorization screen
3. Grant ButterCMS permission to read your basic profile and email address
4. You are redirected back to ButterCMS and logged in automatically

<Info>
  ButterCMS only requests read access to your public profile and verified email address. It does not access your repositories, files, calendar, or any other provider data.
</Info>

## Sign in with Google

### Requirements

* A Google account or Google Workspace (formerly G Suite) account
* Cookies and JavaScript enabled in your browser

### Steps

1. Go to [app.buttercms.com/join/](https://app.buttercms.com/join/)
2. Click **Sign Up With Google**
3. Select the Google account you want to use
4. Review the requested permissions and click **Allow**
5. A ButterCMS account will be created for you, and you will be redirected to your ButterCMS dashboard

<Tip>
  If you manage multiple Google accounts, make sure to select the one associated with your ButterCMS organization's email domain.
</Tip>

### Google Workspace considerations

| Scenario                            | Behavior                                                           |
| ----------------------------------- | ------------------------------------------------------------------ |
| **Personal Google account**         | Works for any ButterCMS plan                                       |
| **Workspace account**               | Works; your Workspace admin does not need to pre-approve ButterCMS |
| **Workspace with app restrictions** | Your admin may need to add ButterCMS as an allowed app             |

## Sign in with GitHub

### Requirements

* A GitHub personal account or membership in a GitHub organization

### Steps

1. Go to [app.buttercms.com/join/](https://app.buttercms.com/join/)
2. Click **Sign Up With GitHub**
3. If prompted, authorize the ButterCMS OAuth application
4. If prompted, provide an email address
5. An account will be created for you, and you will be redirected to your ButterCMS dashboard

### GitHub organization considerations

If your GitHub organization has OAuth app access restrictions enabled, a Workspace admin must approve the ButterCMS OAuth application before members can use GitHub login.

1. A member attempts to sign in with GitHub
2. GitHub shows an "Access restricted" screen
3. The member can request access from their organization owner
4. The organization owner approves ButterCMS in **GitHub Settings > Organization > Third-party access**

## Account matching

When you log in with OAuth for the first time, ButterCMS matches on **email address**:

| Scenario                                        | Result                                                                  |
| ----------------------------------------------- | ----------------------------------------------------------------------- |
| Email matches an existing ButterCMS account     | You are logged in to that account; the provider is linked automatically |
| Email does not match any account                | A new ButterCMS account is created                                      |
| Email matches but is unverified at the provider | Login is blocked until the provider email is verified                   |

## Security considerations

| Topic                     | Details                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Password not required** | OAuth accounts do not need a ButterCMS password, but you can set one in Profile settings                |
| **Token expiry**          | OAuth tokens are short-lived and refreshed automatically; ButterCMS never stores your provider password |
| **MFA**                   | Enabling MFA on your Google or GitHub account also protects your ButterCMS login                        |
| **Revoking access**       | You can revoke ButterCMS's OAuth access from your provider's security settings at any time              |

<Info>
  Revoking access from your provider's side will prevent future OAuth logins to ButterCMS with that provider, but does not delete your ButterCMS account or content.
</Info>