SFDX Auth URL

The SFDX Auth URL is the credential format that enables automated Salesforce authentication. Understanding how it works helps you configure orgs correctly and troubleshoot authentication issues.

What is an SFDX Auth URL?

An SFDX Auth URL is a URL-formatted credential containing OAuth2 tokens that allow non-interactive authentication with Salesforce. It's the standard credential format used by Salesforce CLI and sfp for automation.

URL Format

force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl>

Component	Description
`force://`	Protocol identifier
`clientId`	OAuth2 Connected App Client ID
`clientSecret`	OAuth2 Client Secret (often empty for CLI apps)
`refreshToken`	Long-lived token for obtaining access tokens
`instanceUrl`	Salesforce instance (e.g., `login.salesforce.com`)

Example

force://PlatformCLI::5Aep861_XXXXX.YYYYY@login.salesforce.com

clientId: PlatformCLI (Salesforce CLI's default Connected App)
clientSecret: Empty (not required)
refreshToken: 5Aep861_XXXXX.YYYYY
instanceUrl: login.salesforce.com

How sfp-server Uses SFDX Auth URLs

sfp-server provides centralized, secure storage for SFDX Auth URLs. When you register orgs with the server, credentials are encrypted and stored in Supabase, then decrypted on-demand when needed.

Credential Storage Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    sfp-server Credential Architecture                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   Registration Flow                                                          │
│   ─────────────────                                                          │
│                                                                              │
│   1. Developer authenticates to Salesforce org locally                       │
│      $ sf org login web --alias production                                   │
│                                                                              │
│   2. Register with sfp-server (uploads and encrypts credentials)             │
│      $ sfp server org register --targetorg production                        │
│                                                                              │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────────────────────┐   │
│   │  Local CLI  │────>│ sfp-server  │────>│ Supabase (sfp_salesforce_auth)│  │
│   │ sfdxAuthUrl │     │   API       │     │                             │   │
│   └─────────────┘     └─────────────┘     │  username                   │   │
│                                           │  instance_url               │   │
│                                           │  org_id                     │   │
│                                           │  sfdx_auth_url_encrypted ◄──│   │
│                                           │  (PGP symmetric encryption) │   │
│                                           └─────────────────────────────┘   │
│                                                                              │
│   Retrieval Flow                                                             │
│   ──────────────                                                             │
│                                                                              │
│   1. Request environment with authentication                                 │
│      $ sfp server environment get --name UAT --repository myorg/app \        │
│          --auth-type accessToken --authenticate                              │
│                                                                              │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────────────────────┐   │
│   │    CLI      │────>│ sfp-server  │────>│       Supabase              │   │
│   │             │     │             │     │                             │   │
│   └─────────────┘     └─────────────┘     │  SELECT get_auth_url(...)   │   │
│         │                   │             │  → Decrypt with key         │   │
│         │                   │<────────────│  → Return sfdxAuthUrl       │   │
│         │<──────────────────┘             └─────────────────────────────┘   │
│         │                                                                    │
│         │  accessToken    OR    sfdxAuthUrl                                  │
│         │  (short-lived)        (long-lived)                                 │
│         │                                                                    │
│         ▼                                                                    │
│   Local Salesforce authentication created (alias matches environment name)   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Database Schema

sfp-server stores credentials in the sfp_salesforce_auth table:

Column	Description
`username`	Salesforce username
`instance_url`	Salesforce instance URL
`org_id`	Salesforce Org ID
`org_type`	`production`, `sandbox`, or `devhub`
`sfdx_auth_url_encrypted`	Encrypted SFDX Auth URL
`is_devhub`	Whether org is a DevHub
`is_default`	Default org for its type
`parent_production_username`	Parent org (for JIT sandboxes)
`is_jit_registration`	Whether sandbox uses JIT auth

Encryption

SFDX Auth URLs are encrypted using PGP symmetric encryption before storage:

-- Storage (during registration)
sfdx_auth_url_encrypted = pgp_sym_encrypt(sfdx_auth_url, encryption_key)

-- Retrieval (via stored procedure)
sfdx_auth_url = pgp_sym_decrypt(sfdx_auth_url_encrypted, encryption_key)

The encryption key is configured during sfp-server setup and never leaves the server.

Registering Orgs with sfp-server

Production Orgs and DevHubs

Production orgs and DevHubs require an SFDX Auth URL during registration:

# Step 1: Authenticate locally
sf org login web --alias production

# Step 2: Register with sfp-server
sfp server org register --targetorg production

# For DevHub
sf org login web --alias devhub
sfp server org register --targetorg devhub --is-devhub --is-default

What happens during registration:

CLI extracts the sfdxAuthUrl from local authentication
Validates the connection by querying the org
Sends to sfp-server which encrypts and stores it

Sandboxes (Two Options)

Option 1: Direct Registration (with SFDX Auth URL)

# Authenticate to sandbox directly
sf org login web --alias uat --instance-url https://test.salesforce.com

# Register with sfp-server
sfp server org register --targetorg uat

Option 2: JIT Registration (recommended)

JIT (Just-In-Time) sandboxes don't store credentials - they generate them on-demand via the parent production org:

# Register sandbox by name (no local auth needed)
sfp server org register-sandbox \
  --sandbox-name uat \
  --production-username admin@production.com

What's stored for JIT sandboxes:

sfp_salesforce_auth:
├── username: admin@production--uat.sandbox.com
├── org_type: sandbox
├── sfdx_auth_url_encrypted: NULL  ◄── No stored credentials!
├── parent_production_username: admin@production.com
└── is_jit_registration: true

When credentials are requested, sfp-server:

Retrieves the parent production org's sfdxAuthUrl
Calls Salesforce's sandbox auth API
Returns fresh credentials for the sandbox

See JIT Sandbox Authentication for details.

How Credentials are Returned

sfp-server always returns short-lived access tokens when you access environments. The full SFDX Auth URL (containing the refresh token) never leaves the server.

# Standard usage - always use accessToken
sfp server environment get \
  --name UAT \
  --repository myorg/app \
  --auth-type accessToken \
  --authenticate

Access Token Generation

When you request credentials:

Server retrieves stored sfdxAuthUrl (encrypted)
Uses refresh token to generate new access token
Returns only the short-lived access token (~2 hours)
Refresh token stays on the server

┌──────────────────────────────────────────────────────────────────┐
│                    Access Token Generation                        │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│   Stored (encrypted):    force://PlatformCLI::RefreshToken@...   │
│                                    │                              │
│                                    ▼                              │
│   Server calls:          POST /services/oauth2/token              │
│                          grant_type=refresh_token                 │
│                                    │                              │
│                                    ▼                              │
│   Returns to CLI:        { accessToken, instanceUrl }             │
│                          (NO refresh token exposed)               │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

Exception: Scratch Orgs and Pool-Fetched Sandboxes

For scratch orgs fetched from pools and certain sandbox pool scenarios, the full SFDX Auth URL is returned. This is necessary because:

Scratch org operations may require extended sessions
Pool-fetched environments need independent credential lifecycle
The orgs have limited lifespan anyway (scratch orgs expire)

These are the only scenarios where sfdxAuthUrl leaves the server.

OAuth2 Behind the Scenes

The OAuth2 Flow

When you run sf org login web:

Authorization Request: CLI opens browser to Salesforce authorization endpoint
User Consent: You log in and authorize the Connected App
Authorization Code: Salesforce redirects back with temporary code
Token Exchange: CLI exchanges code for tokens:
- Access Token: Short-lived (~2 hours)
- Refresh Token: Long-lived (until revoked)
SFDX Auth URL Created: CLI packages tokens into the auth URL format

Token Lifecycle

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Refresh Token  │────>│  Access Token   │────>│   API Calls     │
│  (in sfdxAuthUrl)│     │  (2 hours)      │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │
        │                       │ Expires
        │                       ▼
        │               ┌─────────────────┐
        └──────────────>│  New Access     │
           Auto-refresh │  Token          │
                        └─────────────────┘

The refresh token is what makes automation possible. sfp and Salesforce CLI automatically use it to obtain new access tokens when needed.

Troubleshooting

"Invalid SFDX Auth URL"

Verify URL starts with force://
Check for undefined in the refresh token position
Ensure instance URL is valid

"Refresh token expired"

Re-authenticate: sf org login web --alias myOrg
Check Connected App session policies
Re-register with sfp-server

"Decryption failed" (sfp-server)

Encryption key mismatch between registration and retrieval
Re-register the org with current encryption key

"Unable to generate JIT auth"

Verify parent production org is registered
Check sandbox exists and is active
Ensure user has access to the sandbox

Connected Apps - Understanding OAuth clients
Org Registration - Register orgs with sfp-server
JIT Sandbox Authentication - On-demand sandbox credentials
Environments - Link orgs to environments

On this page