> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure credentials and account context

> Select an API key, environment, integration type, and acting account before your first API read.

Connect the [installed CLI](/developer-tools/cli/install) to the environment and account you want to work with. Start with a sandbox API key from the [Straddle dashboard](https://dashboard.straddle.com).

<Steps>
  <Step title="Provide an API key">
    Choose how the CLI receives your key:

    <Tabs>
      <Tab title="Environment variable">
        Set `STRADDLE_API_KEY` in your shell or through your secret manager. Replace the placeholder locally:

        ```bash theme={null}
        export STRADDLE_API_KEY="YOUR_SANDBOX_API_KEY"
        ```

        This variable overrides a token saved with `auth set-token`. Enter keys outside agent prompts and shared scripts; shell history can retain commands that contain them.
      </Tab>

      <Tab title="Saved token">
        Save the key in the CLI's owner-only configuration file:

        ```bash theme={null}
        straddle auth set-token YOUR_SANDBOX_API_KEY
        ```

        The default file is `~/.config/straddle/config.toml`. The command contains the key, so account for shell history when entering it.
      </Tab>
    </Tabs>

    Inspect credential presence and source:

    ```bash theme={null}
    straddle auth status --json
    ```

    `authenticated: true` means a credential is present. `verified: false` means this check hasn't tested it against the API.
  </Step>

  <Step title="Select the environment">
    Use sandbox while building and testing:

    ```bash theme={null}
    export STRADDLE_ENVIRONMENT=sandbox
    ```

    Sandbox is the default. Use `production` with a production key when you're ready for production operations. A configured `STRADDLE_BASE_URL` or `base_url` can override the standard host, so verify the resolved environment in step 4.
  </Step>

  <Step title="Set your integration type">
    Choose the command that matches who owns the customers and payments:

    | Integration | Command | Ownership |
    | - | - | - |
    | Direct business | `straddle setup --type account` | One business collects or sends its own payments. |
    | SaaS platform | `straddle setup --type saas` | Your clients own their customers. |
    | Marketplace | `straddle setup --type marketplace` | Your platform owns the customers. |

    For a SaaS or marketplace platform, select the embedded account for account-level work:

    ```bash theme={null}
    straddle use-account ACCOUNT_ID
    ```

    This selection stays in effect until changed. `straddle use-account --clear` returns to a context without an acting account. Direct business integrations use their key's account and omit this step.
  </Step>

  <Step title="Verify context and an API read">
    Inspect `runtime_context.environment`, `integration_type`, and `acting_account`:

    ```bash theme={null}
    straddle agent-context --pretty
    ```

    Then request one customer from the selected environment:

    ```bash theme={null}
    straddle customers list --page-size 1 --data-source live --no-cache --json
    ```

    A successful response, including an empty list, confirms that the key can perform this operation. Resolve any [authentication or scope error](/developer-tools/cli/troubleshooting) before continuing.
  </Step>
</Steps>

## Choose an account for one command

For a platform payment read, override the saved account with `--account`:

```bash theme={null}
straddle payments --account ACCOUNT_ID --data-source live --no-cache --json
```

The CLI applies `Straddle-Account-Id` by operation and integration type. Marketplace customer, paykey, and Bridge operations use platform ownership. Account-management operations take IDs in the path or body. See [account scoping](/developer-tools/mcp/account-scoping) for the ownership rules.

<Accordion title="Configuration files and reusable profiles">
  Credentials live in `config.toml`; integration type and the saved account live in `platform.toml`. `STRADDLE_CONFIG` selects the credentials file and places `platform.toml` beside it. `STRADDLE_PLATFORM_CONFIG` selects the platform file explicitly. The `--config` flag changes only the credentials file.

  A profile applies saved flag values to one invocation. Inspect it with `straddle profile show PROFILE_NAME`, then use `--profile PROFILE_NAME` on compatible commands. `profile use` prints values; it doesn't activate a persistent profile. Explicit flags override saved values.

  A saved `account` acts as an explicit `--account`, including on commands that reject it. Run `use-account` and profile inspection without `--profile`. Profiles can also supply sync filters or `path-context`; review [sync completeness](/developer-tools/cli/local-data#check-sync-completeness) before using them for analysis.
</Accordion>


## Related topics

- [Work with Straddle from your terminal](/developer-tools/cli/overview.md)
- [Authentication and permissions](/developer-tools/mcp/safety.md)
- [Troubleshoot the Straddle CLI](/developer-tools/cli/troubleshooting.md)
- [Find paykeys that need attention](/playbooks/expiring-paykeys.md)
- [Synchronize and query local data](/developer-tools/cli/local-data.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.