> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Login & Authentication

> Sign in to RunFlow with rf login — browser login by default, API key for automation

The recommended way to authenticate is simply:

```bash theme={null}
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.

```bash theme={null}
rf login
# Opening browser for Runflow login...
#
# ✓ Login successful!
# Profile: acme-corporation
# User: Jane Doe
# Tenant: ACME Corporation (ADMIN)
```

<Info>
  An API key is only needed for **non-interactive** environments (CI/CD,
  scripts, servers without a browser). See
  [API key login](#api-key-login-ci-and-automation) below.
</Info>

## How It Works

1. **Browser opens** on the RunFlow login page (the CLI listens on a local callback, ports `8630`–`8640`).
2. **You sign in** with your RunFlow account (email/password or SSO).
3. **Tenant selection** — if your account has access to multiple tenants, the CLI shows a searchable list to pick the active one.
4. **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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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.

<Info>
  Running RunFlow in your own environment, or switching between several
  environments? See
  [Self-Hosted & Multiple Environments](/cli/self-hosted).
</Info>

## API Key Login (CI and Automation)

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

```bash theme={null}
rf login --api-key sk-1234567890abcdef

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

### Getting an API Key

1. Go to the [RunFlow Portal](https://app.runflow.ai)
2. Navigate to **Settings** → **API Keys**
3. Click **Create New API Key**
4. Copy the key (starts with `sk-...`)

### Example: GitHub Actions

```yaml theme={null}
- name: Login
  run: rf login --api-key ${{ secrets.RUNFLOW_API_KEY }}

- name: Deploy
  run: rf agents deploy
```

<Warning>
  Never hardcode API keys in scripts or commit them to version control. Use
  your CI provider's secret storage.
</Warning>

## 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:

```bash theme={null}
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):

```yaml theme={null}
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
```

<Warning>
  Credentials are stored in plain text in `~/.runflowrc`. Ensure proper file permissions:

  ```bash theme={null}
  chmod 600 ~/.runflowrc
  ```
</Warning>

**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

### Browser Doesn't Open / Login Times Out

```bash theme={null}
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

```bash theme={null}
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](https://app.runflow.ai) first.

### Invalid API Key

```bash theme={null}
rf login --api-key sk-invalid
# Error: Invalid API key
```

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

### Network Connection Error

```bash theme={null}
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)

```bash theme={null}
rf login
# Error: Permission denied: ~/.runflowrc
```

**Solution:**

```bash theme={null}
# Fix file permissions
chmod 600 ~/.runflowrc

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Profiles" icon="users" href="/cli/profiles">
    Manage multiple profiles
  </Card>

  <Card title="Self-Hosted" icon="server" href="/cli/self-hosted">
    Point the CLI at your own installation
  </Card>

  <Card title="Create Agent" icon="plus" href="/cli/create">
    Create your first agent
  </Card>

  <Card title="Test" icon="flask" href="/cli/test">
    Test agents locally
  </Card>
</CardGroup>