Skip to content
Swytchcode logo Swytchcode logo Swytchcode Docs docs

Managed Authentication

Managing API credentials is one of the hardest parts of building AI agents.

Every integration requires authentication, every environment uses different credentials, and storing secrets directly in your project quickly becomes difficult to maintain.

Swytchcode provides Managed Authentication, a secure credential management system that stores, resolves, and injects provider credentials automatically during execution.

Instead of manually handling API keys or OAuth tokens in your application, you connect an account once and let Swytchcode manage the rest.

Why Managed Authentication?

Without managed authentication, developers typically need to:

  • Store API keys in multiple .env files.
  • Copy credentials between projects.
  • Rotate secrets manually.
  • Handle OAuth refresh tokens.
  • Switch credentials between development and production.

Managed Authentication removes this complexity by centralizing credential management.

How It Works

When a tool executes, Swytchcode automatically resolves the correct credentials before making the API request.

AI Agent
      │
      ▼
Execute Tool
      │
      ▼
Resolve Provider
      │
      ▼
Locate Credentials
      │
      ▼
Authenticate Request
      │
      ▼
Execute API

Your application never needs to manually attach authentication headers or manage OAuth refresh flows.

Credential Resolution Order

Whenever a provider requires authentication, Swytchcode searches for credentials using a predictable priority order.

1. Environment Variables
          │
          ▼
2. Managed Credential Store
          │
          ▼
3. Project .env

The first valid credential found is used.

This allows production environments to override local credentials while keeping local development simple.

Connecting a Provider

Connect a provider using:

Terminal window
swy auth connect

To connect a specific provider:

Terminal window
swy auth connect github

or

Terminal window
swy auth connect stripe

Swytchcode automatically detects the authentication method required by the integration.

Depending on the provider, it may:

  • Open an OAuth login flow.
  • Prompt for an API key.
  • Request additional permissions defined by the integration.

OAuth and API Keys

Swytchcode supports both major authentication models.

OAuth Providers

OAuth providers redirect you to the provider’s authentication page.

Examples include:

  • GitHub
  • Google
  • Slack
  • Notion

After authorization, Swytchcode securely stores the credentials and automatically refreshes them when necessary.

API Key Providers

Some providers authenticate using API keys.

Examples include:

  • Stripe
  • Resend
  • Deepgram
  • ElevenLabs

After the key is provided, Swytchcode securely stores it and automatically uses it whenever that provider is called.

Checking Connected Providers

View your connected providers and authentication status using:

Terminal window
swy auth status

list and ls are aliases for the same command (swy auth list, swy auth ls), so either reads naturally depending on the context you’re scripting in.

To see which credentials Swytchcode is currently using for your account (as opposed to provider credentials), run:

Terminal window
swy whoami

The CLI shows the source of each resolved credential, making it easy to verify your current authentication setup.

Disconnecting a Provider

Remove a connected provider’s credentials with:

Terminal window
swy auth disconnect github
swy auth disconnect stripe --local

The --local flag scopes the disconnect to the current project rather than the account-wide managed credential store - reach for it when you want to unhook a provider from one project without affecting other projects that might reuse the same connected account.

Disconnecting doesn’t remove the integration itself from tooling.json - tools stay enabled, they just fail authentication until you reconnect.

Missing Credentials

If a required credential is not available during execution, Swytchcode detects the missing authentication before sending the API request.

In interactive environments, the CLI can prompt you to connect the provider and continue once authentication is complete.

This allows you to install an integration and begin using it without manually configuring every provider in advance.

Secure Credential Storage

Provider credentials live in ~/.swytchcode/credentials.db, a local SQLite database in your home directory - the same place the CLI keeps your login session (auth.json) and MCP token. Nothing here is stored on your project directory or checked into version control; it behaves the same way a .env file or your OS keychain would, except it’s managed for you instead of hand-edited.

This gives you the same guarantees you’d expect from any local secret store:

  • Credentials never leave your machine, except when the CLI attaches them directly to a request going to the actual provider (GitHub, Stripe, etc.) during execution.
  • They’re reused across every project on that machine, so connecting GitHub once means every project you initialize afterward can use it - no copying tokens between .env files.
  • Cloning a repository never exposes provider secrets, because they were never part of the repository in the first place.
  • If Cloud Sync is enabled, it syncs audit metadata to your Swytchcode workspace for dashboard visibility - it never syncs credentials.db or any credential payload.

Your Swytchcode account and your provider credentials are two separate trust boundaries. Signing in to Swytchcode (swy login) - even with a personal email - only creates an authenticated session for the Swytchcode platform itself, tracked in auth.json. It has no bearing on how securely your GitHub, Stripe, or Slack credentials are stored: those live in credentials.db, are resolved locally at execution time, and are never passed through the AI model’s context window. The model calls a tool by canonical ID; the CLI is what looks up and attaches the actual secret.

Local Development

Managed Authentication works alongside local development workflows.

For example:

Development Machine


Environment Variables
        │
        ▼
Managed Credentials
        │
        ▼
Project .env

This allows you to:

  • Override credentials during testing.
  • Share project configuration without sharing secrets.
  • Keep production credentials outside your project.

Best Practices

  • Connect providers once and reuse managed credentials across projects.
  • Use separate accounts for development and production.
  • Prefer OAuth when supported by the provider.
  • Avoid storing secrets inside your repository.
  • Rotate credentials regularly.
  • Grant only the permissions your application requires.
  • Verify connected providers before deploying production workloads.

Next Steps

Authentication Overview

Understand the two authentication layers in Swytchcode - account authentication and provider credentials.

Execution Pipeline

Follow the complete lifecycle of a tool execution, from authentication and policy evaluation to API execution and response handling.

Policies Overview

Learn how Swytchcode policies help enforce safe, predictable, and production-ready API execution.