Targets and Authentication

This feature is in the Early Access stage and under active development. Configuration schemas and behavior are subject to change. We recommend that you do not use this feature in production environments.

Every plan, apply, and pull runs against a target: the Platform service to reconcile. This page covers choosing a target and authenticating to it. For the manifest that can carry a default target, see The Manifest.

Choosing a Target

You can set the target three ways, in order of precedence:

--url on the command line, the explicit platform URL.
--target, a named entry you signed in to with sam auth login, or the reserved name desktop (covered below).
The manifest's target.url. If the manifest has no target.url, the CLI uses its target.name instead: either desktop or the name of a target you signed in to with sam auth login.

Both --url and --target override the address from the manifest's target block, so one manifest can reconcile a local instance during development and a cluster in CI without editing the file. They change only the address. Credentials still follow the manifest's auth block, subject to the SAM_PLATFORM_TOKEN override. For more information, see CI and the SAM_PLATFORM_TOKEN Override.

sam config apply -m manifest.yaml                              # uses the manifest's target.url
sam config apply -m manifest.yaml --url https://staging.example.com   # overrides the address
sam config apply -m manifest.yaml --target prod                # uses the prod login's URL; auth still comes from the manifest

Using the Same Manifest with Other Commands

The sam eval, sam api-key, sam task send, and sam api commands also accept --manifest (-m). They read the same target address and auth block that sam config reads, so you can use one manifest with all of them:

sam config apply -m manifest.yaml
sam eval run my-experiment -m manifest.yaml
sam task send "Summarize today's tickets" -m manifest.yaml -a orchestrator

These commands differ from sam config in the following ways:

The SAM_AUTH_TOKEN environment variable also overrides the manifest's auth block.
For a manifest with no auth block, these commands use a login cached by sam auth login if one is available. They first try the login that target.name names, but only if you created that login for the same address as the target. Then they try a login cached under the target URL's hostname, such as one created with sam auth login platform.example.com. If neither login applies, the command connects without credentials.
These commands never send a named login's token to an address other than the one you signed in to. If the manifest declares auth: {type: oauth} and the resolved address differs from the login's address, the command stops with an error. To fix the error, correct target.url or --url, or sign in again for the new address with sam auth login --target <name> --url <url>.

Passing --url or --target with --manifest changes only the address, so the credentials from a bearer_token block go to the address you pass. Make sure that --url or --target names the address you intend, especially when a script or environment variable supplies the value.

If the manifest's auth block can't produce a token, the command stops with an error rather than falling back to another credential, such as a cached login. For example, the command stops when the environment variable that a bearer_token block names is unset, or when you haven't yet run sam auth login for an oauth target. Set the variable or run sam auth login, then retry.

A Local Instance Needs No Login

A local desktop instance is unauthenticated, so plan, apply, and pull require no sign-in step to reach it. Point at it with the reserved target name desktop, either in the manifest or on the command line:

# manifest.yaml
target:
  name: desktop

sam config apply --target desktop

The name desktop isn't a URL you have to look up: it resolves to whichever address the running desktop app actually published.

Promoting From the Desktop App to a Deployment

Configuration built and tested against the desktop app carries forward as-is: pull it out of the desktop instance, then apply the same files to a real deployment.

sam config pull -o ./pulled --target desktop --manifest-name manifest.yaml
sam config apply -m ./pulled/manifests/manifest.yaml --target prod

The only thing that changes between the two commands is the target. Swap desktop for a deployment's target.name (or --url / --target) and the same agents, models, and entrypoints reconcile against it.

Signing in to a Deployment

For a deployment with sign-in enabled, declare an OAuth target in the manifest and log in once:

# manifest.yaml
target:
  name: prod
  url: https://platform.example.com
  auth:
    type: oauth

sam auth login prod --url https://platform.example.com

The login opens a browser, completes the sign-in flow, and caches the token under the target name. Later plan, apply, and pull runs read that cached token, and refresh it automatically when it expires, so you sign in once rather than per command. The login waits up to 90 seconds for the browser callback; change that with --timeout.

A few companion commands manage cached logins:

sam auth status prod    # show the cached token status and expiry for a target
sam auth list           # list every target you have a cached login for
sam auth logout prod    # revoke and delete the cached credentials for a target

sam auth login requires HTTPS. A bare hostname is upgraded to https://, and an http:// URL is rejected, so a cached token is never sent over an unencrypted connection.

Bearer Tokens

To authenticate with a bearer token instead of the browser flow, set the target's auth.type to bearer_token and name the environment variable that holds the token:

# manifest.yaml
target:
  name: prod
  url: https://platform.example.com
  auth:
    type: bearer_token
    envVar: PLATFORM_TOKEN

sam config reads the token from PLATFORM_TOKEN at run time, so the secret stays in the environment and never in the file.

CI and the SAM_PLATFORM_TOKEN Override

The SAM_PLATFORM_TOKEN environment variable is the highest-priority credential. When it is set, it overrides the cached OAuth token and any bearer-token variable, so a pipeline can supply a service token without changing a manifest that declares an oauth target. The full precedence is:

SAM_PLATFORM_TOKEN, if set.
A cached OAuth token from sam auth login.
The bearer-token variable named by the target's auth.envVar.
Anonymous, for an unauthenticated local instance.

sam config refreshes only a cached OAuth login. It sends SAM_PLATFORM_TOKEN or a bearer-token variable unchanged, and if the Platform service rejects it with 401 Unauthorized, the command fails rather than falling back to a cached login.

sam config plan and sam config apply run non-interactively when you pass --no-interactive, when the CI environment variable is set to any value other than 0 or false, or when standard input or standard error is not a terminal. A non-interactive run fails immediately when no token is available, instead of opening a browser:

SAM_PLATFORM_TOKEN="${SAM_PLATFORM_TOKEN}" \
  sam config apply -m manifests/prod.yaml --no-interactive

Version and Schema Guardrails

Before it changes anything, sam config checks that the CLI and the Platform service are compatible. If the CLI is a full major version behind the platform, the command stops; a smaller lag prints a warning and continues. It also warns once if the platform returns fields the CLI does not recognize, the signal that the CLI is older than the platform. Upgrade the CLI when you see this warning.

To skip the version check, pass --skip-version-check or set SAM_SKIP_VERSION_CHECK=1. Skip it only when you understand the mismatch, because a CLI that is too old can misread the platform's responses.

Loading Environment Variables

sam config auto-loads a .env file from the nearest ancestor directory before it resolves ${VAR} references, so local development picks up credentials without exporting them by hand. A variable already set in the environment keeps its value, so a .env file never replaces credentials that a pipeline already set. Add more files with --env-file (repeatable), whose values override both the environment and the .env file, or opt out of the automatic .env load with --no-dotenv. For how those variables feed substitution, see Secrets and Variables.