Read on newly released AI assisted Insights
flxbl docs
Ctrlk
Learn CD Concepts using LabsslackGitHub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Orgs

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 your@org.com --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
usernamestringOptional

Username of the Salesforce integration user. If not provided, the authenticated username from the SFDX Auth URL will be used.

Example: integration.user@mycompany.com
sfdxAuthUrlstringRequired

SFDX Auth URL (generated using sf org:display -u your@org.com --verbose --json)

Example: force://CLIENT_ID:CLIENT_SECRET:REFRESH_TOKEN@instance.salesforce.com
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"}
skipValidationbooleanOptional

Skip connection validation (for testing purposes only)

Default: false
Responses
201

Organization successfully registered/updated

application/json
usernamestringRequired

Username of the Salesforce org user

instanceUrlstringRequired

Instance URL of the Salesforce org

orgIdstringRequired

Salesforce Organization ID

Example: 00D1a000000xxxxx
organizationTypestringRequired

Type of the Salesforce org

Example: Enterprise Edition
instanceNamestringRequired

Salesforce instance name

Example: NA139
parentProductionUsernamestringOptional

Parent production org username (for JIT sandboxes)

isJitRegistrationbooleanOptional

Whether this org was registered using JIT authentication

isDevHubbooleanOptional

Whether this org is a DevHub

isDefaultbooleanOptional

Whether this is the default DevHub

metadataobjectOptional

Additional metadata stored as key-value pairs

post/sfp/api/auth/salesforce/register

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: admin@mycompany.com
Responses
201

Sandbox successfully registered

application/json
usernamestringRequired

Username of the Salesforce org user

instanceUrlstringRequired

Instance URL of the Salesforce org

orgIdstringRequired

Salesforce Organization ID

Example: 00D1a000000xxxxx
organizationTypestringRequired

Type of the Salesforce org

Example: Enterprise Edition
instanceNamestringRequired

Salesforce instance name

Example: NA139
parentProductionUsernamestringOptional

Parent production org username (for JIT sandboxes)

isJitRegistrationbooleanOptional

Whether this org was registered using JIT authentication

isDevHubbooleanOptional

Whether this org is a DevHub

isDefaultbooleanOptional

Whether this is the default DevHub

metadataobjectOptional

Additional metadata stored as key-value pairs

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

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
usernamestringRequired

Username of the Salesforce org user

instanceUrlstringRequired

Instance URL of the Salesforce org

orgIdstringRequired

Salesforce Organization ID

Example: 00D1a000000xxxxx
organizationTypestringRequired

Type of the Salesforce org

Example: Enterprise Edition
instanceNamestringRequired

Salesforce instance name

Example: NA139
parentProductionUsernamestringOptional

Parent production org username (for JIT sandboxes)

isJitRegistrationbooleanOptional

Whether this org was registered using JIT authentication

isDevHubbooleanOptional

Whether this org is a DevHub

isDefaultbooleanOptional

Whether this is the default DevHub

metadataobjectOptional

Additional metadata stored as key-value pairs

createdAtstring · date-timeRequired

When the org was registered

get/sfp/api/auth/salesforce/orgs

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
usernamestringRequired

Username of the Salesforce org user

instanceUrlstringRequired

Instance URL of the Salesforce org

orgIdstringRequired

Salesforce Organization ID

Example: 00D1a000000xxxxx
organizationTypestringRequired

Type of the Salesforce org

Example: Enterprise Edition
instanceNamestringRequired

Salesforce instance name

Example: NA139
parentProductionUsernamestringOptional

Parent production org username (for JIT sandboxes)

isJitRegistrationbooleanOptional

Whether this org was registered using JIT authentication

isDevHubbooleanOptional

Whether this org is a DevHub

isDefaultbooleanOptional

Whether this is the default DevHub

metadataobjectOptional

Additional metadata stored as key-value pairs

createdAtstring · date-timeRequired

When the org was registered

get/sfp/api/auth/salesforce/org

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
delete/sfp/api/auth/salesforce/org
No content

Update a Salesforce org registration

patch

Updates fields of an existing Salesforce organization registration.

  Updatable fields:
  - isDevHub: Mark/unmark as DevHub. Marking an org as a DevHub verifies it really is one (a Dev-Hub-only ScratchOrgInfo probe) and rejects naming the actual org type if not.
  - isDefault: Mark/unmark as default DevHub (enforces single default constraint)
  - metadata: Update metadata key-value pairs
  - sfdxAuthUrl: Replace the stored credentials. The new URL is validated and the resolved username must match the target org. On success, derived fields (instanceUrl, orgId, instanceName, organizationType) are refreshed from the validation result.

  Note: Setting isDevHub=true always verifies the org is a DevHub, even without a new sfdxAuthUrl. isDefault and metadata updates skip connection validation. sfdxAuthUrl updates always validate.
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"}
sfdxAuthUrlstringOptional

New SFDX Auth URL to replace the stored credentials. The connection is validated and the resolved username must match the target org. Derived fields (instanceUrl, orgId, instanceName, organizationType) are refreshed from the validation result.

Example: force://CLIENT_ID:CLIENT_SECRET:REFRESH_TOKEN@instance.salesforce.com
Responses
200

Organization successfully updated

application/json
usernamestringRequired

Username of the Salesforce org user

instanceUrlstringRequired

Instance URL of the Salesforce org

orgIdstringRequired

Salesforce Organization ID

Example: 00D1a000000xxxxx
organizationTypestringRequired

Type of the Salesforce org

Example: Enterprise Edition
instanceNamestringRequired

Salesforce instance name

Example: NA139
parentProductionUsernamestringOptional

Parent production org username (for JIT sandboxes)

isJitRegistrationbooleanOptional

Whether this org was registered using JIT authentication

isDevHubbooleanOptional

Whether this org is a DevHub

isDefaultbooleanOptional

Whether this is the default DevHub

metadataobjectOptional

Additional metadata stored as key-value pairs

patch/sfp/api/auth/salesforce/org

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
isValidbooleanRequired

Whether the connection is valid

usernamestringRequired

Username tested

orgIdstringOptional

Organization ID if connection successful

organizationTypestringOptional

Organization type if connection successful

instanceNamestringOptional

Instance name if connection successful

errorstringOptional

Error message if connection failed

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

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
usernamestringRequired

Username of the Salesforce org user

instanceUrlstringRequired

Instance URL of the Salesforce org

orgIdstringRequired

Salesforce Organization ID

Example: 00D1a000000xxxxx
organizationTypestringRequired

Type of the Salesforce org

Example: Enterprise Edition
instanceNamestringRequired

Salesforce instance name

Example: NA139
parentProductionUsernamestringOptional

Parent production org username (for JIT sandboxes)

isJitRegistrationbooleanOptional

Whether this org was registered using JIT authentication

isDevHubbooleanOptional

Whether this org is a DevHub

isDefaultbooleanOptional

Whether this is the default DevHub

metadataobjectOptional

Additional metadata stored as key-value pairs

createdAtstring · date-timeRequired

When the org was registered

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

Generate a short-lived access token for a Salesforce org

post

Mints a fresh, short-lived access token so callers never handle the long-lived refresh token. Provide exactly one of:

    - `username` — a registered org, or an unregistered **scratch** pool org (resolved via the pool instance's stored auth).
    - `sandboxName` — an unregistered **pool sandbox**; the parent production org is auto-resolved (optionally scoped by `repository`) and the token is minted just-in-time through its connected app.

    Designed for CI/CD: the token is short-lived (typically 1-2 hours) and usable directly with the CLI:

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

    Security: the refresh token stays on the server, tokens expire quickly, and each request mints a fresh one.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
usernamestringOptional

Username of a registered or scratch-pool Salesforce org. Provide this OR sandboxName.

sandboxNamestringOptional

Name of a pool sandbox (parent production org auto-resolved). Provide this OR username.

repositorystringOptional

Optional repository identifier (owner/repo) to scope the sandbox parent-org lookup.

Responses
200

Access token generated successfully

application/json
accessTokenstringRequired

Salesforce access token (short-lived)

Example: 00D1a000000xxxxx!ARcAQ...
instanceUrlstringRequired

Salesforce instance URL

Example: https://mycompany.my.salesforce.com
usernamestringRequired

Username of the Salesforce org

orgIdstringRequired

Salesforce Organization ID

Example: 00D1a000000xxxxx
isDevHubbooleanOptional

Whether this org is a DevHub

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

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
accessTokenstringRequired

Salesforce access token (short-lived)

Example: 00D1a000000xxxxx!ARcAQ...
instanceUrlstringRequired

Salesforce instance URL

Example: https://mycompany.my.salesforce.com
usernamestringRequired

Username of the Salesforce org

orgIdstringRequired

Salesforce Organization ID

Example: 00D1a000000xxxxx
isDevHubbooleanOptional

Whether this org is a DevHub

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

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
403

Forbidden - Requires role: member, application

No content
get/sfp/api/auth/salesforce/frontdoor
403

Forbidden - Requires role: member, application

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: admin@example.com
Responses
201

Successfully authenticated to sandbox

application/json
sandboxNamestringRequired

Name of the authenticated sandbox

Example: dev1
sandboxUsernamestringRequired

Username in the sandbox

Example: admin@dev1.example.com
accessTokenstringRequired

Access token for the sandbox

Example: 00D...
instanceUrlstringRequired

Instance URL for the sandbox

Example: https://dev1.sandbox.salesforce.com
frontDoorUrlstringRequired

Front door URL for direct login

Example: https://dev1.sandbox.salesforce.com/secur/frontdoor.jsp?sid=00D...
productionOrgobjectRequired

Production org details

Example: {"username":"admin@example.com","orgId":"00D...","instanceUrl":"https://example.my.salesforce.com"}
post/sfp/api/auth/salesforce/sandbox/authenticate

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: test-xyz@example.com.scratch
devhubUsernamestringOptional

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

Example: admin@devhub.com
Responses
201

Successfully authenticated to scratch org

application/json
scratchOrgUsernamestringRequired

Username of the authenticated scratch org

Example: test-xyz@example.com.scratch
accessTokenstringRequired

Access token for the scratch org

Example: 00D...
instanceUrlstringRequired

Instance URL for the scratch org

Example: https://power-business-1234-dev-ed.scratch.my.salesforce.com
frontDoorUrlstringRequired

Front door URL for direct login

Example: https://power-business-1234-dev-ed.scratch.my.salesforce.com/secur/frontdoor.jsp?sid=00D...
sfdxAuthUrlstringOptional

SFDX Auth URL for the scratch org (if available)

Example: force://...
orgIdstringRequired

Org ID of the scratch org

Example: 00D...
devhubOrgobjectRequired

DevHub org details

Example: {"username":"admin@devhub.com","orgId":"00D...","instanceUrl":"https://devhub.my.salesforce.com"}
post/sfp/api/auth/salesforce/scratch/authenticate

Last updated

Was this helpful?