Authentication

Authentication in Swytchcode is divided into two independent authentication planes. Although they both involve credentials, they serve completely different purposes. Understanding the difference is essential before working with integrations, Managed Authentication, or the Execution Pipeline.

Authentication

Account authentication identifies who you are to Swytchcode.

Provider credentials authorize what external APIs your agent can access.

Account Authentication

Account authentication is used whenever you interact with Swytchcode itself (see CLI Authentication).

This includes operations such as:

Logging into the CLI
Accessing the Swytchcode registry
Checking your account
Downloading integrations
Upgrade approvals
Telemetry and account-specific services

It is not used when executing tools against third-party APIs.

Authentication Methods

Swytchcode checks authentication using the following order.

1. Service Token

For automation, CI/CD pipelines, and AI agents, Swytchcode first checks for a service token.

SWYTCHCODE_TOKEN

This token is read directly from the process environment.

Swytchcode intentionally does not load this value from a project .env file, making it suitable for secure deployment environments.

2. User Session

If no service token is available, Swytchcode falls back to the local user session created during login.

A session is created using:

swy login
swy login --open   # also opens the browser automatically

The CLI authenticates using a secure OAuth device flow and saves the session to ~/.swytchcode/auth.json. You can sign in through the CLI or visit app.swytchcode.com to manage your account in the browser.

The session automatically refreshes when required, allowing you to continue working without repeatedly logging in.

Authentication Commands

The CLI provides several commands for managing your account authentication.

Command	Purpose
`swy login`	Sign in to your Swytchcode account (or visit app.swytchcode.com).
`swy logout`	Remove the current local session.
`swy whoami`	Display the active authentication state.

Provider Credentials

Provider credentials are completely separate from your Swytchcode account.

They are only used when executing tools against external services.

For example:

GitHub
Stripe
Slack
Gmail
Notion
HubSpot
Twilio

When your AI agent executes a tool, Swytchcode resolves the required provider credentials before sending the request.

Your Swytchcode account credentials are never used to authenticate requests to external providers.

Provider credentials are managed with a separate set of commands from account authentication:

Command	Purpose
`swy auth connect [provider]`	Connect a provider account or API key (OAuth flow or inline prompt). With no argument, lists which providers your installed integrations still need.
`swy auth status`	List connected provider accounts (aliases: `list`, `ls`).
`swy auth disconnect <provider> [--local]`	Disconnect a provider’s connected account.

The full connect/disconnect workflow, including how OAuth vs. API-key providers differ, is covered in Managed Authentication.

Workspaces

Separately from both of the above, a project can be pinned to a specific Swytchcode workspace - the account/organization it’s billed and audited under. Most projects just use whichever workspace you’re signed into, but if you work across multiple teams or clients you can pin a project explicitly:

swy auth workspace <alias-or-uuid>

# equivalent, shorter alias
swy auth link <alias-or-uuid>

See Workspace linking for details on where this is stored.

Credential Resolution

When a tool executes, Swytchcode resolves provider credentials using a predictable priority order.

Environment Variables
        │
        ▼
Managed Credential Store (/guides/managed-authentication/)
        │
        ▼
Project .env

The first valid credential found is used.

This resolution order makes it easy to override credentials in CI while still supporting local development.

Environment Variables

Environment variables have the highest priority.

This is the recommended approach for:

Production deployments
CI/CD pipelines
Secret management systems
Containerized applications

Managed Credential Store

Swytchcode provides an encrypted local credential store for securely managing provider credentials.

Credentials stored here can be reused across multiple projects without placing secrets inside your project directory.

The managed credential store is covered in detail in the Managed Authentication guide.

Project `.env`

During local development, credentials can also be loaded from the project’s .env file.

This provides a convenient development experience while keeping production deployments separate.

See Setting SWYTCHCODE_TOKEN in the CLI reference for recommended patterns and examples.

Authentication During Execution

Authentication happens automatically whenever a tool executes.

AI Agent
      │
      ▼
Select Tool
      │
      ▼
Resolve Provider Credentials
      │
      ▼
Authenticate Request
      │
      ▼
Execute API
      │
      ▼
Return Response

The runtime automatically determines which credentials should be used for the requested provider before making the API call.

Authentication Best Practices

Follow these recommendations when working with authentication:

Keep your Swytchcode account separate from provider credentials.
Use environment variables for production deployments whenever possible.
Store reusable local credentials in the managed credential store instead of project files.
Never commit secrets to source control.
Rotate provider credentials regularly.
Grant only the minimum permissions required for your application.
Use separate credentials for development and production environments.

Next Steps

Managed Authentication

Learn how Swytchcode securely stores, resolves, and manages provider credentials during tool execution.

Execution Pipeline

See how every tool execution flows through validation, authentication, policies, retries, and API execution.

CLI Authentication

Explore the CLI authentication model, including account login, provider authentication, and credential resolution.