Org Registration

Org registration stores Salesforce credentials centrally on sfp-server, enabling team members and CI/CD pipelines to access orgs without managing individual credentials.

Why Register Orgs?

Without Registration	With Registration
Each developer manages their own credentials	Credentials stored centrally
CI/CD secrets for each org	Single server token for CI/CD
No credential rotation coordination	Centralized credential management
Risk of stale/invalid credentials	Server validates and refreshes tokens

Registration Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Org Registration Flow                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. Developer authenticates locally                            │
│      sf org login web --alias myOrg                             │
│                                                                 │
│   2. Register with server                                       │
│      sfp server org register --targetorg myOrg                  │
│                  │                                              │
│                  ▼                                              │
│   3. Server stores encrypted credentials                        │
│      ┌─────────────────────────────────┐                        │
│      │ sfp-server (Supabase)           │                        │
│      │ ┌─────────────────────────────┐ │                        │
│      │ │ sfp_salesforce_auth         │ │                        │
│      │ │ - username                  │ │                        │
│      │ │ - instance_url              │ │                        │
│      │ │ - sfdx_auth_url (encrypted) │ │                        │
│      │ │ - org_id                    │ │                        │
│      │ │ - is_devhub                 │ │                        │
│      │ └─────────────────────────────┘ │                        │
│      └─────────────────────────────────┘                        │
│                                                                 │
│   4. Team members can now access the org                        │
│      sfp server org login --username admin@myorg.com            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Registering Orgs

Basic Registration

First, authenticate locally, then register:

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

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

Register as DevHub

Mark an org as your DevHub for scratch org operations:

sfp server org register --targetusername devhub --devhub

Register as Default DevHub

Set as the default DevHub (only one org can have this):

sfp server org register --targetusername devhub --devhub --default

Register with Metadata

Add custom metadata for organization:

sfp server org register \
  --targetusername production \
  --metadata '{"region": "US", "tier": "enterprise"}'

Listing Registered Orgs

sfp server org list

Output:

┌──────────────────────────┬────────────────────────────────┬─────────┬─────────┐
│ Username                 │ Instance URL                   │ DevHub  │ Default │
├──────────────────────────┼────────────────────────────────┼─────────┼─────────┤
│ admin@production.com     │ https://myorg.my.salesforce.com│ No      │ Yes     │
│ admin@devhub.com         │ https://devhub.salesforce.com  │ Yes     │ Yes     │
│ admin@uat.sandbox.com    │ https://myorg--uat.sandbox.com │ No      │ No      │
└──────────────────────────┴────────────────────────────────┴─────────┴─────────┘

Accessing Registered Orgs

Team members can authenticate to registered orgs without having the original credentials:

# Authenticate locally using server-stored credentials
sfp server org login --username admin@production.com

This retrieves credentials from the server and authenticates locally.

Get Default DevHub

sfp server org get-default-devhub

Credential Storage Security

Encryption

SFDX Auth URLs are encrypted before storage:

-- Stored encrypted using PGP symmetric encryption
sfdx_auth_url_encrypted = pgp_sym_encrypt(auth_url, encryption_key)

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

Access Control

Only users with owner or application roles can retrieve credentials
Members can see org metadata but not credentials
All access is logged in the audit trail

What's Stored

Field	Stored	Encrypted
Username	Yes	No
Instance URL	Yes	No
Org ID	Yes	No
SFDX Auth URL	Yes	Yes
Org Type	Yes	No
Metadata	Yes	No

Sandbox Registration

Standard Sandbox Registration

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

# Register
sfp server org register --targetusername uat

Register with Parent (for JIT)

Link a sandbox to its parent production org for JIT authentication:

sfp server org register-sandbox \
  --sandboxname uat \
  --productionusername admin@production.com

This enables JIT Sandbox Authentication - the sandbox can be authenticated on-demand via the production org.

Updating Registrations

Update Credentials

When org credentials change (e.g., after re-authentication):

# Re-authenticate locally
sf org login web --alias production

# Update server registration
sfp server org update --targetusername production

Update Metadata

sfp server org update \
  --targetusername admin@production.com \
  --metadata '{"region": "EU", "tier": "enterprise"}'

Removing Registrations

sfp server org delete --username admin@oldorg.com

Deleting an org registration will break any environments linked to that org. Update or delete affected environments first.

CI/CD Integration

Use Registered Orgs in Pipelines

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      SFP_SERVER_URL: ${{ secrets.SFP_SERVER_URL }}
      SFP_SERVER_TOKEN: ${{ secrets.SFP_SERVER_TOKEN }}
    steps:
      - name: Login to Production
        run: |
          sfp server org login --username admin@production.com --alias production

      - name: Deploy
        run: |
          sfp install --targetorg production --artifactdir ./artifacts

Troubleshooting

"Org not found"

# Verify org is registered
sfp server org list

# Re-register if needed
sfp server org register --targetusername myOrg

"Unable to retrieve credentials"

Verify you have owner or application role
Check if the SFDX Auth URL is still valid
Re-register the org if credentials expired

"Invalid SFDX Auth URL"

The stored credentials may be stale:

# Re-authenticate locally
sf org login web --alias myOrg

# Update registration
sfp server org update --targetusername myOrg

Server Authentication - Authenticate with sfp-server
Environments - Link registered orgs to environments
JIT Sandbox - On-demand sandbox authentication
SFDX Auth URL - Understanding auth URLs

On this page