Orgs | sfp server | flxbl docs

Register or update a Salesforce org

post

Registers a new Salesforce organization or updates an existing one.

      Requirements:
      - sfdxAuthUrl is required (Generate using: sf org:display -u [email protected] --verbose --json)
      - The connection is validated before registration
      - instanceUrl is optional and will be extracted from sfdxAuthUrl if not provided
      
      Optional fields:
      - isDevHub: Mark this org as a DevHub (default: false)
      - isDefault: Mark this as the default DevHub - only one org can have this set (default: false)
      - metadata: Additional metadata as key-value pairs in JSON format
      
      If an org with the same username exists, it will be updated.
      
      For sandbox registrations without sfdxAuthUrl, use /auth/salesforce/register-sandbox-by-name instead.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

instanceUrlstringOptional

Instance URL of the Salesforce org (will be extracted from sfdxAuthUrl if not provided)

Example: https://mycompany.my.salesforce.comPattern: https://*.salesforce.com

usernamestringRequired

Username of the Salesforce integration user

Example: [email protected]

sfdxAuthUrlstringRequired

SFDX Auth URL (generated using sf org:display -u [email protected] --verbose --json)

Example: force://CLIENT_ID:CLIENT_SECRET:[email protected]

isDevHubbooleanOptional

Whether this org is a DevHub

Default: false

isDefaultbooleanOptional

Whether this is the default DevHub (only one org can have this set to true)

Default: false

metadataobjectOptional

Additional metadata stored as key-value pairs

Example: {"environment":"production","region":"us-west"}

Responses

201

Organization successfully registered/updated

application/json

400

Invalid input or connection failed

post

/sfp/api/auth/salesforce/register

POST /sfp/api/auth/salesforce/register HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 277

{
  "instanceUrl": "https://mycompany.my.salesforce.com",
  "username": "[email protected]",
  "sfdxAuthUrl": "force://CLIENT_ID:CLIENT_SECRET:[email protected]",
  "isDevHub": false,
  "isDefault": false,
  "metadata": {
    "environment": "production",
    "region": "us-west"
  }
}

{
  "username": "text",
  "instanceUrl": "text",
  "orgId": "00D1a000000xxxxx",
  "organizationType": "Enterprise Edition",
  "instanceName": "NA139",
  "parentProductionUsername": "text",
  "isJitRegistration": true,
  "isDevHub": true,
  "isDefault": true,
  "metadata": {}
}

Register a Salesforce sandbox using production org credentials

post

Registers a Salesforce sandbox organization using credentials from an already registered production org.

      Requirements:
      - The production org must be registered first using /auth/salesforce/register
      - The sandbox must be created by the same user whose credentials are stored for the production org
      - The system will validate the sandbox and retrieve all necessary details automatically
      
      This endpoint is specifically for sandboxes where you don't have the sfdxAuthUrl.
      Just-in-time authentication will be used when accessing the sandbox.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

sandboxNamestringRequired

Name of the sandbox to register

Example: dev1

productionUsernamestringRequired

Username of the production org (must be already registered)

Example: [email protected]

Responses

201

Sandbox successfully registered

application/json

400

Invalid input or validation failed

404

Production org not found

post

/sfp/api/auth/salesforce/register-sandbox-by-name

POST /sfp/api/auth/salesforce/register-sandbox-by-name HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "sandboxName": "dev1",
  "productionUsername": "[email protected]"
}

{
  "username": "text",
  "instanceUrl": "text",
  "orgId": "00D1a000000xxxxx",
  "organizationType": "Enterprise Edition",
  "instanceName": "NA139",
  "parentProductionUsername": "text",
  "isJitRegistration": true,
  "isDevHub": true,
  "isDefault": true,
  "metadata": {}
}

List registered Salesforce orgs

get

Returns a list of all registered Salesforce organizations with optional filtering.

  Filter options:
  - type: Filter by organization type (e.g., "Production", "Sandbox")
  - devhub: Filter to show only DevHub organizations
  - metadata: Filter by metadata key-value pairs using either format:
    - Comma-separated: key1=value1,key2=value2
    - JSON object: {"key1":"value1","key2":"value2"}
  
  Response includes DevHub status, default flag, and metadata for each org.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

typestringOptional

Filter organizations by type (e.g., "Developer Edition", "Production", "Sandbox")

devhubbooleanOptional

Filter to show only DevHub organizations

metadatastringOptional

Filter by metadata key-value pairs. Format: key1=value1,key2=value2 or JSON object

Responses

200

List of registered organizations

application/json

get

/sfp/api/auth/salesforce/orgs

GET /sfp/api/auth/salesforce/orgs HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of registered organizations

[
  {
    "username": "text",
    "instanceUrl": "text",
    "orgId": "00D1a000000xxxxx",
    "organizationType": "Enterprise Edition",
    "instanceName": "NA139",
    "parentProductionUsername": "text",
    "isJitRegistration": true,
    "isDevHub": true,
    "isDefault": true,
    "metadata": {},
    "createdAt": "2025-12-18T17:39:57.492Z"
  }
]

Get details of a specific Salesforce org

get

Returns detailed information about a specific registered Salesforce organization. Owner role and application tokens can request authentication credentials.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

usernamestringRequired

Username of the Salesforce org to retrieve, or sandbox name for sandboxes with no sfdxAuthUrl

authTypestring · enumOptional

Type of authentication to return: "accessToken" (short-lived, default) or "sfdxAuthUrl" (long-lived refresh token for long-running operations)

Possible values:

Responses

200

Organization details

application/json

404

Organization not found

get

/sfp/api/auth/salesforce/org

GET /sfp/api/auth/salesforce/org?username=text HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "username": "text",
  "instanceUrl": "text",
  "orgId": "00D1a000000xxxxx",
  "organizationType": "Enterprise Edition",
  "instanceName": "NA139",
  "parentProductionUsername": "text",
  "isJitRegistration": true,
  "isDevHub": true,
  "isDefault": true,
  "metadata": {},
  "createdAt": "2025-12-18T17:39:57.492Z"
}

Delete a Salesforce org registration

delete

Removes the stored credentials for a Salesforce organization

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

usernamestringRequired

Username of the Salesforce org to delete, or sandbox name for sandboxes with no sfdxAuthUrl

Responses

200

Organization successfully deleted

No content

404

Organization not found

delete

/sfp/api/auth/salesforce/org

DELETE /sfp/api/auth/salesforce/org?username=text HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a Salesforce org registration

patch

Updates metadata fields of an existing Salesforce organization registration without re-validating the connection.

  Updatable fields:
  - isDevHub: Mark/unmark as DevHub
  - isDefault: Mark/unmark as default DevHub (enforces single default constraint)
  - metadata: Update metadata key-value pairs
  
  Note: This endpoint does not validate the Salesforce connection, it only updates metadata attributes.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

usernamestringRequired

Username of the Salesforce org to update

Body

isDevHubbooleanOptional

Whether this org is a DevHub

isDefaultbooleanOptional

Whether this is the default DevHub (only one org can have this set to true)

metadataobjectOptional

Additional metadata stored as key-value pairs

Example: {"environment":"production","region":"us-west"}

Responses

200

Organization successfully updated

application/json

404

Organization not found

patch

/sfp/api/auth/salesforce/org

PATCH /sfp/api/auth/salesforce/org?username=text HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "isDevHub": true,
  "isDefault": true,
  "metadata": {
    "environment": "production",
    "region": "us-west"
  }
}

{
  "username": "text",
  "instanceUrl": "text",
  "orgId": "00D1a000000xxxxx",
  "organizationType": "Enterprise Edition",
  "instanceName": "NA139",
  "parentProductionUsername": "text",
  "isJitRegistration": true,
  "isDevHub": true,
  "isDefault": true,
  "metadata": {}
}

Test connection to a REGISTERED Salesforce org

post

Tests if the stored credentials for a registered org are still valid.

    **Note**: This endpoint only works for orgs that are registered in the system.
    It validates that the stored sfdxAuthUrl can still be used to authenticate.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

usernamestringRequired

Username of the Salesforce org to test, or sandbox name for sandboxes with no sfdxAuthUrl

Responses

200

Connection test results

application/json

404

Organization not found

post

/sfp/api/auth/salesforce/test-connection

POST /sfp/api/auth/salesforce/test-connection?username=text HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "isValid": true,
  "username": "text",
  "orgId": "text",
  "organizationType": "text",
  "instanceName": "text",
  "error": "text"
}

Get the default DevHub organization

get

Returns the org marked as the default DevHub with authentication details for owner role and application tokens.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

authTypestring · enumOptional

Type of authentication to return: "accessToken" (short-lived, default) or "sfdxAuthUrl" (long-lived refresh token for long-running operations)

Possible values:

Responses

200

Default DevHub organization details

application/json

404

No default DevHub found

get

/sfp/api/auth/salesforce/default-devhub

GET /sfp/api/auth/salesforce/default-devhub HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "username": "text",
  "instanceUrl": "text",
  "orgId": "00D1a000000xxxxx",
  "organizationType": "Enterprise Edition",
  "instanceName": "NA139",
  "parentProductionUsername": "text",
  "isJitRegistration": true,
  "isDevHub": true,
  "isDefault": true,
  "metadata": {},
  "createdAt": "2025-12-18T17:39:57.492Z"
}

Generate a short-lived access token for a REGISTERED Salesforce org

post

Generates a new access token using the stored refresh token (sfdxAuthUrl) for a registered org.

    **Important**: This endpoint is for orgs that are already registered in the system.
    For unregistered sandboxes or scratch orgs, use:
    - `POST /auth/salesforce/sandbox/authenticate` for unregistered sandboxes
    - `POST /auth/salesforce/scratch/authenticate` for unregistered scratch orgs

    This endpoint is designed for CI/CD workflows where you need to authenticate to Salesforce
    without exposing the long-lived refresh token. The access token returned is short-lived
    (typically 1-2 hours) and can be used directly with the CLI:

    sfp org login --access-token <token> --instance-url <url>

    Security benefits:
    - Refresh token stays securely on the server
    - Access tokens expire quickly, limiting exposure if compromised
    - Each request generates a fresh token

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

usernamestringRequired

Username of the Salesforce org to generate access token for

Responses

200

Access token generated successfully

application/json

404

Organization not found

post

/sfp/api/auth/salesforce/access-token

POST /sfp/api/auth/salesforce/access-token?username=text HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "accessToken": "00D1a000000xxxxx!ARcAQ...",
  "instanceUrl": "https://mycompany.my.salesforce.com",
  "username": "text",
  "orgId": "00D1a000000xxxxx",
  "isDevHub": true
}

Generate a short-lived access token for the default DevHub

post

Generates a new access token for the default DevHub organization.

    This is a convenience endpoint for CI/CD workflows that need DevHub access.
    Use the returned access token with:

    sfp org login --access-token <token> --instance-url <url> --set-default-dev-hub

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Access token generated successfully

application/json

404

No default DevHub found

post

/sfp/api/auth/salesforce/default-devhub/access-token

POST /sfp/api/auth/salesforce/default-devhub/access-token HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "accessToken": "00D1a000000xxxxx!ARcAQ...",
  "instanceUrl": "https://mycompany.my.salesforce.com",
  "username": "text",
  "orgId": "00D1a000000xxxxx",
  "isDevHub": true
}

Get Salesforce org frontdoor URL

get

Returns or redirects to a frontdoor URL for a sandbox or scratch org.

    The endpoint will check in order:
    1. Registered orgs with stored auth URLs
    2. Pool instances (if repository is provided)
    3. Dynamic generation using production org credentials
    
    For pool instances, the repository parameter is required to ensure the correct sandbox is accessed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

targetstringRequired

Scratch org username, sandbox name, or pool instance name

repositorystringOptional

Repository identifier (org/repo) to search for pool instances

prodOrgstringOptional

Production org username (for dynamic sandbox generation)

redirectbooleanOptional

Redirect to frontdoor URL (default true)

Responses

200Success

No content

get

/sfp/api/auth/salesforce/frontdoor

GET /sfp/api/auth/salesforce/frontdoor?target=text HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200Success

No content

Authenticate to an unregistered Salesforce sandbox

post

Generates a short-lived access token for a Salesforce sandbox that is NOT registered in the system.

        **Important**: This endpoint is for sandboxes that are not registered as orgs.
        For registered orgs (including registered sandboxes), use:
        - `POST /auth/salesforce/access-token?username=<sandbox-username>` to generate access tokens

        How it works:
        1. Uses the registered production org's credentials to perform OAuth exchange
        2. Calls the Salesforce /sandboxAuth API to get an auth code
        3. Exchanges the auth code for an access token
        4. Returns the access token (short-lived, typically 1-2 hours)

        Requirements:
        - The production org must be registered using /auth/salesforce/register first
        - The sandbox must be created from the production org

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

sandboxNamestringRequired

The name of the sandbox to authenticate

Example: dev1

productionUsernamestringOptional

Username of the production org (must be registered). If not provided, the service will cycle through all registered production orgs to find one that has this sandbox.

Example: [email protected]

Responses

201

Successfully authenticated to sandbox

application/json

400

Bad Request - sandbox is already registered (use /auth/salesforce/access-token instead)

401

Unauthorized

404

Production org not found

post

/sfp/api/auth/salesforce/sandbox/authenticate

POST /sfp/api/auth/salesforce/sandbox/authenticate HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "sandboxName": "dev1",
  "productionUsername": "[email protected]"
}

{
  "sandboxName": "dev1",
  "sandboxUsername": "[email protected]",
  "accessToken": "00D...",
  "instanceUrl": "https://dev1.sandbox.salesforce.com",
  "frontDoorUrl": "https://dev1.sandbox.salesforce.com/secur/frontdoor.jsp?sid=00D...",
  "productionOrg": {
    "username": "[email protected]",
    "orgId": "00D...",
    "instanceUrl": "https://example.my.salesforce.com"
  }
}

Authenticate to an unregistered Salesforce scratch org

post

Generates a short-lived access token for a Salesforce scratch org that is NOT registered in the system.

        **Important**: This endpoint is for scratch orgs that are not registered as orgs.
        For registered orgs (including registered scratch orgs), use:
        - `POST /auth/salesforce/access-token?username=<scratch-org-username>` to generate access tokens

        How it works:
        1. Queries the DevHub's ScratchOrgInfo object for the scratch org
        2. Retrieves the SfdxAuthUrl__c custom field (must be populated)
        3. Uses the stored refresh token to generate a fresh access token
        4. Returns the access token (short-lived, typically 1-2 hours)

        Requirements:
        - A DevHub org must be registered using /auth/salesforce/register first
        - The scratch org must have SfdxAuthUrl__c populated in its ScratchOrgInfo record
        - If devhubUsername is not provided, the system will try all registered DevHub orgs

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

scratchOrgUsernamestringRequired

Username of the scratch org to authenticate

Example: [email protected]

devhubUsernamestringOptional

Username of the DevHub org (optional - if not provided, will try all registered DevHub orgs)

Example: [email protected]

Responses

201

Successfully authenticated to scratch org

application/json

400

Bad Request - scratch org is already registered (use /auth/salesforce/access-token instead), or SfdxAuthUrl__c not available

401

Unauthorized

404

DevHub org not found or no DevHub orgs registered

post

/sfp/api/auth/salesforce/scratch/authenticate

POST /sfp/api/auth/salesforce/scratch/authenticate HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "scratchOrgUsername": "[email protected]",
  "devhubUsername": "[email protected]"
}

{
  "scratchOrgUsername": "[email protected]",
  "accessToken": "00D...",
  "instanceUrl": "https://power-business-1234-dev-ed.scratch.my.salesforce.com",
  "frontDoorUrl": "https://power-business-1234-dev-ed.scratch.my.salesforce.com/secur/frontdoor.jsp?sid=00D...",
  "sfdxAuthUrl": "force://...",
  "orgId": "00D...",
  "devhubOrg": {
    "username": "[email protected]",
    "orgId": "00D...",
    "instanceUrl": "https://devhub.my.salesforce.com"
  }
}

Good afternoon

Register or update a Salesforce org

Register a Salesforce sandbox using production org credentials

List registered Salesforce orgs

Get details of a specific Salesforce org

Delete a Salesforce org registration

Update a Salesforce org registration

Test connection to a REGISTERED Salesforce org

Get the default DevHub organization

Generate a short-lived access token for a REGISTERED Salesforce org

Generate a short-lived access token for the default DevHub

Get Salesforce org frontdoor URL

Authenticate to an unregistered Salesforce sandbox

Authenticate to an unregistered Salesforce scratch org