# 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:

```bash
# 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:

```bash
sfp server org register --targetusername devhub --devhub
```

### Register as Default DevHub

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

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

### Register with Metadata

Add custom metadata for organization:

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

## Listing Registered Orgs

```bash
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

### Login via Server

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

```bash
# 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

```bash
sfp server org get-default-devhub
```

## Credential Storage Security

### Encryption

SFDX Auth URLs are encrypted before storage:

```sql
-- 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

```bash
# 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:

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

This enables [JIT Sandbox Authentication](/flxbl/sfp/sfp-community/environment-management/environments/jit-sandbox.md) - the sandbox can be authenticated on-demand via the production org.

## Updating Registrations

### Update Credentials

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

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

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

### Update Metadata

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

## Removing Registrations

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

{% hint style="warning" %}
Deleting an org registration will break any environments linked to that org. Update or delete affected environments first.
{% endhint %}

## CI/CD Integration

### Use Registered Orgs in Pipelines

```yaml
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"

```bash
# 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:

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

# Update registration
sfp server org update --targetusername myOrg
```

## Related Topics

* [Server Authentication](/flxbl/sfp/sfp-community/auth-management/server-authentication.md) - Authenticate with sfp-server
* [Environments](/flxbl/sfp/sfp-community/environment-management/environments.md) - Link registered orgs to environments
* [JIT Sandbox](/flxbl/sfp/sfp-community/environment-management/environments/jit-sandbox.md) - On-demand sandbox authentication
* [SFDX Auth URL](/flxbl/sfp/sfp-community/auth-management/sfdx-auth-url.md) - Understanding auth URLs


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/sfp-community/environment-management/environments/org-registration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.