Skip to content
Swytchcode logo Swytchcode logo Swytchcode Docs docs

Authentication

Before your AI agent can interact with external services, Swytchcode needs permission to access those services on your behalf.

Authentication allows you to securely connect your accounts, such as GitHub, Slack, Google, Stripe, or Notion, so that API requests can be executed without manually managing tokens in your application.

Once an integration is authenticated, Swytchcode automatically uses the appropriate credentials whenever a tool is executed.

How authentication works

Authentication in Swytchcode happens in two stages.

  1. Sign in to Swytchcode
  2. Connect the third party integrations your project needs

Signing in authenticates you with the Swytchcode platform.

Connecting an integration authorizes Swytchcode to execute API requests for that specific service.

Sign in
    │
    ▼
Connect Integration
    │
    ▼
Store Credentials Securely
    │
    ▼
Execute API Requests

You only need to connect an integration once unless you revoke access or your credentials expire.

Sign in to Swytchcode

To start using the CLI, sign in to your Swytchcode account.

You can also run npx swytchcode to invoke the CLI without installing it globally - on first run this will open your browser and guide you to create an account and sign in automatically (new users are redirected to the account creation flow).

You can sign in through the CLI or visit app.swytchcode.com to manage your account in the browser.

Terminal window
swy login

The CLI opens your browser and starts a secure authentication flow.

After signing in successfully, your terminal session becomes authenticated and can access your Swytchcode projects.

You can verify your current session at any time.

Terminal window
swy whoami

This displays the account currently signed in to the CLI.

When you’re done with a session - for example on a shared machine - sign out to delete the saved session:

Terminal window
swy logout

Connect an integration

After signing in, connect the services your project needs.

For example, to connect GitHub:

Terminal window
swy auth connect github

Depending on the integration, Swytchcode will either:

  • Open a secure browser based OAuth flow
  • Prompt for an API key if the service uses API key authentication

Once authentication is complete, the integration is ready to execute tools.

You can repeat this process for any supported service.

Examples include:

Terminal window
swy auth connect github


swy auth connect slack


swy auth connect stripe


swy auth connect notion

Check connected integrations

To see which integrations are currently connected, run:

Terminal window
swy auth status

This displays information such as:

  • Connected integrations
  • Authentication status
  • Active account
  • Credential type

swy auth status also has two shorter aliases if they’re easier to remember: swy auth list and swy auth ls.

Checking the authentication status is useful when troubleshooting execution failures or verifying project setup.

Switch between accounts

Some developers work with multiple accounts for the same service.

For example:

  • Personal GitHub account
  • Organization GitHub account

Reconnect the provider to switch which account is active for the current project.

Terminal window
swy auth connect github

The CLI walks you through authenticating again and lets you choose which account should be active for the current project.

This makes it easy to work across personal, team, and production environments.

Disconnect an integration

If you no longer want Swytchcode to access a service, disconnect the integration.

Terminal window
swy auth disconnect github

Removing an integration revokes its local credentials and prevents future tool executions until it is connected again.

By default this also revokes access on the Swytchcode backend. If you only want to forget the credential on this machine and keep the connection active elsewhere, pass --local:

Terminal window
swy auth disconnect github --local

Disconnecting an integration does not uninstall it from your project. It only removes the associated authentication.

Switch workspaces

If you work across multiple teams or clients, a project is tied to a single Swytchcode workspace at a time. Check or change which one is active with:

Terminal window
swy auth workspace
swy auth workspace <alias-or-uuid>

swy auth workspace with no argument shows the current workspace; passing an alias or UUID switches the project to it. The alias swy auth link does the same thing.

Secure credential storage

Swytchcode is designed so that developers do not need to manually manage access tokens inside configuration files.

When you authenticate with an integration, the CLI writes the credential to ~/.swytchcode/credentials.db - a local SQLite database in your home directory, not inside your project. It’s the same idea as keeping secrets in a .env file or your OS keychain rather than in source: it lives on your machine, outside version control, and the CLI reads it back only at the moment a request actually needs it.

This is a different trust boundary from your Swytchcode account session. Signing in with swy login (using whatever email you signed up with) just authenticates you to the Swytchcode platform - that session is tracked separately in ~/.swytchcode/auth.json. It has no bearing on how a connected provider’s credentials are stored: those go straight into credentials.db, get resolved locally by the CLI at execution time, and are never exposed to the AI model itself - the model only ever sees a canonical ID like github.issues.create, never the token behind it.

This approach provides several benefits:

  • Credentials remain outside your project files and out of version control.
  • Authentication can be reused across every project on the same machine.
  • AI agents never receive direct access to your secrets.
  • Cloud Sync, if enabled, only syncs audit metadata to your workspace - never credentials.db or any credential payload.

You should never copy access tokens into source code or configuration files unless specifically required by the integration. For the full picture of how credentials are resolved and injected during execution, see Managed Authentication.

Expired credentials

OAuth access tokens can expire over time.

If an API request requires reauthentication, Swytchcode automatically prompts you to reconnect the affected integration.

After reauthentication completes, execution continues without requiring you to repeat your workflow from the beginning.

Best practices

Connect only the integrations your project requires.

Use separate accounts for development and production environments whenever possible.

Review your connected integrations periodically using swy auth status.

Disconnect integrations that are no longer in use.

Never share access tokens or credentials with other users.

Now that your account and provider credentials are configured, you’re ready to start building with Swytchcode.

What's Next?

Projects

Learn how Swytchcode organizes project configuration, policies, and execution settings.

Integrations

Install and manage the providers available to your project.

Tools

Enable trusted methods and workflows that your AI agents can execute.

Execute Tools

Execute tools through the Swytchcode runtime with authentication, retries, and policy enforcement.

Policy Rules

Define custom policies to control how and when tools are allowed to execute.

Managed Authentication

See how credentials are resolved, stored, and injected during execution.