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

# Authentication

> Connect FileFetch to your Salesforce organization

## Overview

FileFetch uses the Salesforce SOAP API to authenticate with your Salesforce org. You can connect to Production, Sandbox, or custom domain instances using username, password, and security token authentication.

<Note>
  **Security First**: Your credentials are stored securely in your operating system's keychain (macOS Keychain or Windows Credential Manager) and never leave your computer.
</Note>

## Salesforce Environments

FileFetch supports three types of Salesforce environments:

<Tabs>
  <Tab title="Production">
    **Production Organizations**

    Use this for live Salesforce orgs.

    * **URL**: `https://login.salesforce.com`
    * **Use Case**: Production data, real customer information
    * **Recommended For**: Exporting files from your main Salesforce org

    <Warning>
      Be careful when exporting from Production. Ensure you have proper permissions and understand what data you're downloading.
    </Warning>
  </Tab>

  <Tab title="Sandbox">
    **Sandbox Organizations**

    Use this for test, development, or UAT environments.

    * **URL**: `https://test.salesforce.com`
    * **Use Case**: Testing, development, training
    * **Recommended For**: Testing FileFetch before using in Production

    <Tip>
      If you're new to FileFetch, we recommend testing in a Sandbox first to familiarize yourself with the export process.
    </Tip>
  </Tab>

  <Tab title="Custom Domain">
    **Custom/My Domain**

    Use this if your org has a custom domain or My Domain enabled.

    * **URL**: `https://yourdomain.my.salesforce.com`
    * **Use Case**: Organizations with My Domain or custom login URLs
    * **Example**: `https://acme.my.salesforce.com`

    <Info>
      You must include the full URL including `https://`. FileFetch will validate the URL format before attempting login.
    </Info>
  </Tab>
</Tabs>

## Getting Your Security Token

Salesforce requires a security token when logging in from external applications like FileFetch.

<Steps>
  <Step title="Log in to Salesforce">
    Go to your Salesforce org in a web browser
  </Step>

  <Step title="Navigate to Settings">
    Click your profile icon (top right) → **Settings**
  </Step>

  <Step title="Find Personal Information">
    In the left sidebar, search for or navigate to:
    **My Personal Information → Reset My Security Token**
  </Step>

  <Step title="Reset Token">
    Click **Reset Security Token**

    Salesforce will send a new security token to your email address
  </Step>

  <Step title="Copy Token">
    Check your email for the security token and copy it

    <Warning>
      Keep your security token confidential. Anyone with your username, password, and token can access your Salesforce org.
    </Warning>
  </Step>
</Steps>

<Tip>
  **Can't find the Reset Security Token option?**

  Your org may have IP restrictions enabled. If your IP address is whitelisted in Salesforce, you may not need a security token. Try leaving it blank. If that doesn't work, contact your Salesforce administrator.
</Tip>

## Signing In

<Steps>
  <Step title="Launch FileFetch">
    Open the FileFetch application
  </Step>

  <Step title="Select Environment">
    Choose your Salesforce environment type from the dropdown
  </Step>

  <Step title="Enter Credentials">
    Fill in your login information:

    * **Username**: Your Salesforce username (usually your email)
    * **Password**: Your Salesforce password
    * **Security Token**: The token from your email

    <Info>
      **Note**: You enter the password and security token in **separate fields**. Do not concatenate them.
    </Info>
  </Step>

  <Step title="Authenticate">
    Click **Sign In**

    FileFetch will:

    1. Connect to Salesforce using the SOAP API
    2. Verify your credentials
    3. Store them securely in your system keychain
    4. Retrieve your session token for API calls
  </Step>
</Steps>

## Credential Storage

FileFetch stores your credentials locally using your operating system's secure credential storage:

<Tabs>
  <Tab title="macOS">
    **macOS Keychain**

    Credentials are stored in the macOS Keychain, the same secure storage used by Safari, Mail, and other native apps.

    * **Location**: Keychain Access app
    * **Service Name**: `app.filefetch.filefetch`
    * **Security**: Protected by your Mac user password
    * **Encrypted**: Yes, using macOS encryption

    To view or delete stored credentials:

    1. Open **Keychain Access** (Applications → Utilities)
    2. Search for `filefetch`
    3. Right-click the entry to view or delete
  </Tab>

  <Tab title="Windows">
    **Windows Credential Manager**

    Credentials are stored in Windows Credential Manager, the same secure storage used by Windows apps and services.

    * **Location**: Control Panel → Credential Manager
    * **Service Name**: `app.filefetch.filefetch`
    * **Security**: Protected by your Windows user password
    * **Encrypted**: Yes, using Windows DPAPI

    To view or delete stored credentials:

    1. Open **Control Panel → Credential Manager**
    2. Click **Windows Credentials**
    3. Find the FileFetch entry to view or delete
  </Tab>
</Tabs>

## Troubleshooting Login Issues

<AccordionGroup>
  <Accordion title="Invalid username, password, security token, or user locked out">
    **Possible Causes**:

    * Incorrect username, password, or security token
    * User account is locked or deactivated
    * Password has expired

    **Solutions**:

    1. Verify your username is correct (usually your email)
    2. Double-check your password
    3. Make sure you're using the latest security token from your email
    4. Try logging in via the Salesforce website to verify credentials
    5. Contact your Salesforce administrator if account is locked
  </Accordion>

  <Accordion title="Login timeout or connection failed">
    **Possible Causes**:

    * Network connectivity issues
    * Firewall blocking Salesforce API
    * Incorrect environment selected
    * Custom domain URL incorrect

    **Solutions**:

    1. Check your internet connection
    2. Verify you selected the correct environment (Production/Sandbox/Custom)
    3. For custom domains, ensure URL is correct and includes `https://`
    4. Check if your firewall is blocking connections to `*.salesforce.com`
    5. Try accessing Salesforce in a browser to verify connectivity
  </Accordion>

  <Accordion title="Security token not working / 'invalid grant' error">
    **Possible Causes**:

    * Old or expired security token
    * Token was reset but you're using the old one
    * IP restrictions require no token, but you're providing one

    **Solutions**:

    1. Reset your security token in Salesforce
    2. Check your email for the new token
    3. Copy the entire token (no spaces)
    4. If your IP is trusted, try leaving the token field blank
  </Accordion>

  <Accordion title="Two-factor authentication (2FA) required">
    **Current Status**: FileFetch does not currently support OAuth 2.0 or 2FA.

    **Workaround**:

    1. Add your IP address to the Salesforce trusted IP ranges
    2. This allows API access without 2FA
    3. Contact your Salesforce administrator for assistance

    <Note>
      OAuth 2.0 support is planned for a future release.
    </Note>
  </Accordion>

  <Accordion title="User does not have API access">
    **Cause**: Your Salesforce user profile doesn't have API access enabled.

    **Solution**:
    Contact your Salesforce administrator to enable "API Enabled" permission on your user profile.
  </Accordion>
</AccordionGroup>

## Logging Out

To log out of FileFetch:

1. Click your user profile in the bottom left of the sidebar
2. Click the **logout icon** (arrow)
3. Your session will end and credentials remain stored for next time

<Tip>
  Logging out doesn't delete your stored credentials. They remain in your keychain for quick re-authentication next time.
</Tip>

## Switching Orgs

To connect to a different Salesforce org:

1. Log out of your current session
2. The login screen will appear
3. Select the new environment
4. Enter credentials for the new org
5. Sign in

FileFetch will update the stored credentials for the new org.

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Strong Passwords" icon="lock">
    Ensure your Salesforce password is strong and unique
  </Card>

  <Card title="Protect Your Token" icon="shield">
    Never share your security token with others
  </Card>

  <Card title="Regular Token Resets" icon="rotate">
    Reset your token if you suspect it's been compromised
  </Card>

  <Card title="Monitor Login History" icon="eye">
    Check Salesforce login history regularly for suspicious activity
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Run Your First Query" icon="magnifying-glass" href="/query-builder">
    Learn to find files using the Query Builder
  </Card>

  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Complete walkthrough from login to first export
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.