> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# Authentication commands

> Islo authentication commands for login and logout using OAuth 2.0 with PKCE, plus API key support.

Authenticate before selecting a factory or connecting an event provider. A [Line integration trigger](/concepts/triggers) also needs its GitHub, Slack, or Linear connection.

Islo supports two authentication methods:

1. **OAuth 2.0** (default) - Browser-based login for interactive use
2. **API Keys** - For CI/CD, scripts, and programmatic access

## islo login

Authenticate with Islo via browser-based OAuth flow.

**Syntax:**

```bash
islo login
```

**Behavior:**

1. Starts a local HTTP server on port 9876 (override with `ISLO_OAUTH_PORT`).
2. Opens your default browser to the Descope authorization URL.
3. You authenticate via Google, email, or SSO.
4. Descope redirects to localhost with an authorization code.
5. The CLI exchanges the code for access and refresh tokens.
6. Tokens are stored securely on your system (see [Token Storage](#token-storage)).

**Troubleshooting:**

If the browser doesn't open automatically:

1. Copy the URL printed in the terminal.
2. Paste it into your browser manually.
3. Complete the login flow.
4. The CLI catches the callback automatically.

## islo logout

Clear stored authentication tokens.

**Syntax:**

```bash
islo logout
```

## islo switch

Switch between organizations you belong to.

**Syntax:**

```bash
islo switch
```

**Behavior:**

1. Prints your current organization.
2. Opens a browser for an OAuth flow that lets you pick a different org.
3. Replaces your stored credentials with the new org's tokens.

After the flow, run `islo status` to confirm the new org.

## Integrations Login

Connect external services so your Factory can receive work from your tools and Agents can act in connected services. Connections have personal or team scope, as listed below. For access policies and credential injection on a Machine, see [Gateways](/cli/gateways).

**Syntax:**

```bash
islo login --tool <service>
```

**Supported integrations:**

* `github` — GitHub repo and code access (personal + team)
* `slack` — Slack workspace notifications (team)
* `linear` — Linear project management and issues (team)
* `notion` — Notion workspace for notes and docs (team)
* `atlassian` — Atlassian (Jira, Confluence) (team)
* `anthropic` (alias: `claude`) — Anthropic API key for Claude models (personal)
* `cursor` — Cursor API key for Cursor CLI in sandboxes (personal)
* `openai` — OpenAI API key for GPT models (personal)

"Personal" connections apply only to your user. "Team" connections apply to everyone in the org.

**Examples:**

```bash
# Connect GitHub for private repo access
islo login --tool github

# Connect Anthropic for Claude agent
islo login --tool anthropic   # or: islo login --tool claude
```

Integration tokens are stored securely and used automatically when needed.

## islo status

Show your authentication state, connected integrations, project configuration, and sandboxes.

**Syntax:**

```bash
islo status
```

**Output:**

Sections for authentication state, connected integrations, project configuration from `islo.yaml`, environment/secret guidance, and your sandboxes.

**Example output:**

```
Authentication
  Status: Logged in
  Org: Acme Corp
  Tier: team
  Expires: <Date-Time>

Connected Integrations
  github ✓ (user)
  github ✓ (team)
  linear ✓ (team)
  anthropic ✓ (user)
  Integrations power Islo features, but sandbox CLIs such as 'gh' may still need their own token or login inside the sandbox.

Project Configuration
  Memory: 4096 MB

Environment & Secrets
  Persistent sandbox env comes from 'islo.yaml' env plus any '--env KEY=VALUE' flags.
  Agent-specific credentials should come from integrations or explicit '--env KEY=VALUE' flags when needed.

Your Sandboxes
  my-project       running
  backend-dev      running
  api-tests        stopped

  Tip: Run 'islo ls --all' to see team sandboxes
```

## Token Storage

Islo stores tokens securely using platform-specific backends:

| Backend                    | Platform | Description                                 |
| -------------------------- | -------- | ------------------------------------------- |
| macOS Keychain             | macOS    | System keychain with service `islo.dev.cli` |
| Windows Credential Manager | Windows  | Windows credential store                    |
| Linux Secret Service       | Linux    | System keyring                              |
| File                       | All      | Fallback: `~/.islo/auth.json`               |

## Token Types

| Token         | Lifetime     | Purpose                  |
| ------------- | ------------ | ------------------------ |
| Access Token  | \~15 minutes | API authentication (JWT) |
| Refresh Token | Long-lived   | Obtain new access tokens |

The CLI automatically refreshes expired access tokens using the refresh token. If the refresh token expires, you'll need to run `islo login` again.

## OAuth Port Configuration

The OAuth callback uses port 9876 by default. To use a different port:

```bash
export ISLO_OAUTH_PORT=9999
islo login
```

## Session Expiration

The CLI refreshes expired access tokens automatically. When the refresh token itself expires or becomes invalid, the next command prints a message asking you to login again. Re-authenticate with:

```bash
islo login
```

See [Troubleshooting → Authentication](/cli/troubleshooting/#authentication) for the full message variants.

## API Key Authentication

For CI/CD pipelines, scripts, and other non-interactive callers, use an API key instead of OAuth. Set `ISLO_API_KEY` in the environment and the CLI skips the browser flow:

```bash
export ISLO_API_KEY=islo_key_…
islo ls
```

### API Key vs OAuth

| Feature          | OAuth            | API Key                                     |
| ---------------- | ---------------- | ------------------------------------------- |
| Interactive use  | Yes              | No                                          |
| CI/CD pipelines  | No               | Yes                                         |
| Browser required | Yes              | No                                          |
| Token refresh    | Automatic        | N/A                                         |
| Scope            | User permissions | Key permissions (inherits from the creator) |

See **[API Keys](/cli/api-keys)** for creating, listing, rotating, and using keys.