> For the complete documentation index, see [llms.txt](https://documentation.grax.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.grax.com/other/permissions-and-access/oauth-overview.md).

# OAuth Overview

## OAuth Connection Overview

### What is OAuth?

OAuth (Open Authorization) is an industry-standard protocol that allows GRAX to securely access your Salesforce data without storing your credentials. When you connect GRAX to Salesforce, OAuth handles the authentication and authorization process.

### How GRAX Uses OAuth

GRAX uses OAuth for two purposes:

1. [**Integration User Connection**](#integration-user): A dedicated Salesforce user that performs backup, restore, and archive operations
2. [**End User Single Sign-On (SSO)**](/other/permissions-and-access/roles-for-end-users.md): Individual users log into the GRAX Application using their Salesforce credentials. Note: End-user access is validated by the Integration User's OAuth connection, so the Integration User must include the `id` scope (or `profile`, `email`) in its OAuth token.

### OAuth Connection Architecture

GRAX uses Salesforce's OAuth authorization code flow, with `hq.grax.com` as the OAuth client:

1. Your browser is redirected to your Salesforce domain, where you log in and approve access.
2. Salesforce redirects to `hq.grax.com`, which exchanges the authorization code for tokens using GRAX's app credentials.
3. The GRAX backend retrieves the result from `hq.grax.com` over an authenticated server connection. Tokens never pass through your browser.
4. For the integration user, GRAX keeps the encrypted credentials it needs to stay connected. For end-user SSO, the user's Salesforce token isn't stored.

**Key Security Features:**

* All data stores are encrypted
* Token exchanges originate from IP address `3.232.229.75`
* GRAX respects Salesforce field and record-level security

For complete technical details, see the [Authentication documentation](https://documentation.grax.com/technology/security/security#authentication).

### Common OAuth Scenarios

#### Initial Connection

To connect GRAX to Salesforce using OAuth:

1. Navigate to your GRAX Application
2. Select Production or Sandbox based on your org type
3. Click "Establish OAuth Connection to Salesforce"
4. Complete the Salesforce login flow
5. Log in with your individual user via SSO

**Learn more:** [Connecting Salesforce](/other/settings/connecting-salesforce.md)

#### After Sandbox Refresh

If GRAX loses connection after a sandbox refresh, you'll receive reset emails with a link to reconnect.

**Learn more:** [Sandbox Refresh](/other/settings/sandbox-refresh.md) and [Handling Loss of Salesforce Connection](/other/settings/sandbox-refresh.md#post-refresh-reconfiguration)

#### After Enhanced Domain Changes

After Salesforce Enhanced Domain changes, navigate to your GRAX Application URL with `/web` appended and sign in with Salesforce to reestablish the connection.

**Learn more:** [Troubleshooting documentation](/other/troubleshooting.md#does-grax-support-enhanced-domains)

#### OAuth Errors During Connection

If you encounter OAuth errors:

1. Verify "Approve Uninstalled Connected Apps" permission on the connecting user
2. Check that the GRAX Connected App is installed
3. Verify network connectivity and IP whitelisting

**Learn more:** [Connected App troubleshooting](/other/permissions-and-access/connected-app.md#troubleshooting)

### Related Documentation

* [Authentication](https://documentation.grax.com/technology/security/security#oauth-flow) - Complete OAuth flow and security details
* [Connected App](/other/permissions-and-access/connected-app.md) - Installation and configuration
* [Integration User](/other/permissions-and-access/integration-user.md) - User requirements and setup
* [Connecting Salesforce](/other/settings.md#salesforce-panel) - Step-by-step connection guide
* [Network Requirements](https://documentation.grax.com/technology/requirements/network-requirements) - Required network access for GRAX Deployments
* [Troubleshooting](/other/troubleshooting.md) - Common issues and solutions