Login & Authentication

The recommended way to authenticate is simply:

rf login

This opens your browser for RunFlow login (OIDC with PKCE). No API key needed — you sign in with your regular RunFlow account, pick a tenant if you have more than one, and the CLI saves everything as a profile.

rf login
# Opening browser for Runflow login...
#
# ✓ Login successful!
# Profile: acme-corporation
# User: Jane Doe
# Tenant: ACME Corporation (ADMIN)

An API key is only needed for non-interactive environments (CI/CD, scripts, servers without a browser). See API key login below.

How It Works

Browser opens on the RunFlow login page (the CLI listens on a local callback, ports 8630–8640).
You sign in with your RunFlow account (email/password or SSO).
Tenant selection — if your account has access to multiple tenants, the CLI shows a searchable list to pick the active one.
Profile saved — access token, refresh token, tenant, and API URL are stored in ~/.runflowrc. The profile is named after the tenant unless you pass --profile.

Tokens are refreshed automatically — you won’t be asked to log in again until the refresh token expires or you run rf logout. Verify your session at any time:

rf whoami

Options

Option	Description	Example
`--profile <name>`	Save under a custom profile name (defaults to the tenant name)	`rf login --profile staging`
`--api <url>`	Target a self-hosted installation (remembered in the profile)	`rf login --api https://api.acme.com`
`--api-key <key>`	Skip the browser and authenticate with an API key (CI/automation)	`rf login --api-key sk-xxx...`

Switching Tenants

If your account has access to multiple tenants, switch between them anytime — no new login required:

rf switch
# → searchable list of your tenants

rf switch acme-corp
# ✓ Switched to tenant: ACME Corporation

Multiple Environments

Each profile remembers its own API URL and identity provider, so cloud and self-hosted installs live side by side:

# RunFlow Cloud
rf login --profile cloud

# Self-hosted staging
rf login --profile staging --api https://api.staging.yourcompany.com

When you pass --api, the CLI discovers the installation’s login provider from the server and remembers the URL in the profile, so later logins and refreshes reuse it automatically.

Running RunFlow in your own environment, or switching between several environments? See Self-Hosted & Multiple Environments.

For pipelines, scripts, and headless machines, authenticate with an API key instead of the browser:

rf login --api-key sk-1234567890abcdef

# Optionally under a named profile
rf login --api-key sk-xxx... --profile ci

Getting an API Key

Go to the RunFlow Portal
Navigate to Settings → API Keys
Click Create New API Key
Copy the key (starts with sk-...)

Example: GitHub Actions

- name: Login
  run: rf login --api-key ${{ secrets.RUNFLOW_API_KEY }}

- name: Deploy
  run: rf agents deploy

Never hardcode API keys in scripts or commit them to version control. Use your CI provider’s secret storage.

Signing Out

rf logout clears the stored tokens but keeps the API URL, provider, and tenant, so signing back in is a single rf login with no flags:

rf logout               # current profile
rf logout staging       # a specific profile
rf logout --all         # every profile

Configuration File

Credentials are stored per profile in ~/.runflowrc (YAML):

currentProfile: acme-corporation
profiles:
  # Browser (OIDC) login
  acme-corporation:
    token: eyJhbGciOi...
    refreshToken: v1.MRr...
    tokenExpiresAt: 2026-08-01T12:00:00.000Z
    email: jane@acme.com
    tenantId: tenant_abc123
    tenantName: ACME Corporation
    api: https://api.runflow.ai/api/v1/runtime
  # API key login (CI)
  ci:
    apiKey: sk-xxx...
    tenantId: tenant_abc123
    api: https://api.runflow.ai/api/v1/runtime

Credentials are stored in plain text in ~/.runflowrc. Ensure proper file permissions:

chmod 600 ~/.runflowrc

Recommendations:

Never share your ~/.runflowrc file
Don’t commit .runflowrc to version control
Prefer browser login for humans; reserve API keys for automation
Use separate API keys for dev/staging/prod
Rotate keys regularly and revoke unused ones from the portal

Troubleshooting

rf login
# Error: Login timed out. Please try again.

Solution:

Check that a browser is available on the machine — on headless servers, use rf login --api-key instead
Make sure nothing blocks localhost ports 8630–8640 (firewall, VPN)
Try again — the login link waits a limited time for the callback

No Tenant Found

rf login
# Error: Login failed: No tenant information found in your account.

Solution: Your user isn’t linked to any tenant yet. Ask your workspace admin for an invite, or sign up at the RunFlow Portal first.

Invalid API Key

rf login --api-key sk-invalid
# Error: Invalid API key

Solution: Check your API key in the portal and try again.

Network Connection Error

rf login
# Error: Cannot connect to API

Solution:

Check your internet connection
Verify the API URL is correct (--api for self-hosted)
Check if the API is accessible (firewall, VPN)

Permission Denied (Config File)

rf login
# Error: Permission denied: ~/.runflowrc

Solution:

# Fix file permissions
chmod 600 ~/.runflowrc

# Or remove and recreate
rm ~/.runflowrc
rf login

Next Steps

Profiles

Manage multiple profiles

Self-Hosted

Point the CLI at your own installation

Create Agent

Create your first agent

Test

Test agents locally

Getting Started

CLI

Core Concepts

Real-World Examples

Advanced

Configuration

Extending Runflow

Help & Support

Login & Authentication

How It Works

Options

Switching Tenants

Multiple Environments

Getting an API Key

Example: GitHub Actions

Signing Out

Configuration File

Troubleshooting

No Tenant Found

Invalid API Key

Network Connection Error

Permission Denied (Config File)

Next Steps

Profiles

Self-Hosted

Create Agent

Test

​How It Works

​Options

​Switching Tenants

​Multiple Environments

​API Key Login (CI and Automation)

​Getting an API Key

​Example: GitHub Actions

​Signing Out

​Configuration File

​Troubleshooting

​Browser Doesn’t Open / Login Times Out

​No Tenant Found

​Invalid API Key

​Network Connection Error

​Permission Denied (Config File)

​Next Steps

Profiles

Self-Hosted

Create Agent

Test

How It Works

Options

Switching Tenants

Multiple Environments

API Key Login (CI and Automation)

Getting an API Key

Example: GitHub Actions

Signing Out

Configuration File

Troubleshooting

Browser Doesn’t Open / Login Times Out

No Tenant Found

Invalid API Key

Network Connection Error

Permission Denied (Config File)

Next Steps